mirror of
https://github.com/ruvnet/RuView
synced 2026-06-26 13:03:19 +00:00
ruv
f5d787ccde
Per ADR-115 §9.4 (maintainer ACK on #776), v0.7.0 ships **3 starter blueprints**. This commit goes further: all **8** of the catalog proposed in §3.12.2 land as standalone YAML files under `examples/ha-blueprints/`, ready to import into HA. ## Blueprints 1. Notify on possible distress → possible_distress 2. Dim hallway when sleeping → someone_sleeping 3. Wake routine on bed exit → bed_exit (time-window-gated) 4. Alert on elderly inactivity → elderly_inactivity_anomaly (with optional escalation chain) 5. Meeting lights + presence mode → meeting_in_progress (activates a HA scene) 6. Bathroom fan while occupied → bathroom_occupied (privacy-mode-safe; zone-derived) 7. Escalate on fall-risk crossing → fall_risk_elevated (numeric_state trigger) 8. Auto-arm security when not active → group(room_active) + no_movement (composed; multi-room sense) Each blueprint: - Uses HA's blueprint schema (https://www.home-assistant.io/docs/blueprint/schema/) - Declares typed `selector:` for every input (entity-domain-constrained where applicable) - Carries a `source_url` for HACS-style re-import - Includes `mode: single` + `max_exceeded: silent` where appropriate so transient retriggers don't spam - Includes a `cooldown_minutes` / `confirm_minutes` / `ack_timeout_min` parameter where time-debouncing matters ## Validator (`scripts/validate-ha-blueprints.py`) Pure-Python validator that: - Registers no-op constructors for HA's `!input` and `!secret` YAML tags (PyYAML doesn't know them) - Asserts every file has a top-level `blueprint:` mapping with `name`/`description`/`domain` - Asserts `domain` is `automation` or `script` - Asserts at least one declared `input` - Asserts at least one of `trigger`/`action`/`sequence` is present Exits 0 only when all 8 validate. Local run: python scripts/validate-ha-blueprints.py All 8 HA Blueprints validate OK ## CI integration `.github/workflows/mqtt-integration.yml` gains a new `Validate HA Blueprints` step that runs the Python validator before the cargo test phases — fails the workflow on any malformed blueprint in a PR. ## Privacy-mode coverage table 5 of 8 blueprints are unconditionally privacy-mode-safe (no biometric dependency in the state derivation). The other 3 depend on inferred states that themselves derive from biometrics — the inferred state still publishes under `--privacy-mode` (per ADR §3.12.3) but the operator should audit the use case in regulated contexts. Full table in `examples/ha-blueprints/README.md`. Refs #776, PR #778. Co-Authored-By: claude-flow <ruv@ruv.net>
115 lines
3.2 KiB
Python
115 lines
3.2 KiB
Python
#!/usr/bin/env python3
|
|
"""Validate every YAML file under examples/ha-blueprints/.
|
|
|
|
HA Blueprints use the `!input` YAML tag, which stock PyYAML doesn't
|
|
know how to construct. We register a no-op constructor for it so we
|
|
can still safe_load the files and assert on their structure.
|
|
|
|
Exits 0 if all blueprints are well-formed, non-zero otherwise. Intended
|
|
to run in CI on every PR that touches examples/ha-blueprints/.
|
|
|
|
Usage:
|
|
python scripts/validate-ha-blueprints.py
|
|
"""
|
|
|
|
from __future__ import annotations
|
|
|
|
import glob
|
|
import sys
|
|
from pathlib import Path
|
|
|
|
import yaml
|
|
|
|
|
|
class InputTag(str):
|
|
"""No-op holder for HA `!input` markers — we don't expand them, just
|
|
verify the file parses."""
|
|
|
|
|
|
def _input_constructor(loader, node):
|
|
return InputTag(loader.construct_scalar(node))
|
|
|
|
|
|
def _secret_constructor(loader, node):
|
|
return f"<!secret {loader.construct_scalar(node)}>"
|
|
|
|
|
|
yaml.SafeLoader.add_constructor("!input", _input_constructor)
|
|
yaml.SafeLoader.add_constructor("!secret", _secret_constructor)
|
|
|
|
|
|
REQUIRED_BLUEPRINT_KEYS = {"name", "description", "domain"}
|
|
ALLOWED_DOMAINS = {"automation", "script"}
|
|
|
|
|
|
def validate(path: Path) -> list[str]:
|
|
"""Return a list of issues; empty list means the blueprint is valid."""
|
|
issues: list[str] = []
|
|
try:
|
|
with path.open(encoding="utf-8") as fh:
|
|
doc = yaml.safe_load(fh)
|
|
except yaml.YAMLError as e:
|
|
return [f"YAML parse error: {e}"]
|
|
except OSError as e:
|
|
return [f"could not open: {e}"]
|
|
|
|
if not isinstance(doc, dict):
|
|
return ["top-level must be a mapping"]
|
|
|
|
bp = doc.get("blueprint")
|
|
if not isinstance(bp, dict):
|
|
issues.append("missing `blueprint` mapping at top level")
|
|
return issues
|
|
|
|
missing = REQUIRED_BLUEPRINT_KEYS - bp.keys()
|
|
if missing:
|
|
issues.append(f"missing blueprint keys: {', '.join(sorted(missing))}")
|
|
|
|
domain = bp.get("domain")
|
|
if domain not in ALLOWED_DOMAINS:
|
|
issues.append(
|
|
f"unsupported blueprint.domain={domain!r}; allowed: {ALLOWED_DOMAINS}"
|
|
)
|
|
|
|
if not isinstance(bp.get("input"), dict) or not bp["input"]:
|
|
issues.append("blueprint.input must declare at least one input")
|
|
|
|
# The automation body must contain at least one of: trigger,
|
|
# action, sequence (script body).
|
|
if "trigger" not in doc and "action" not in doc and "sequence" not in doc:
|
|
issues.append(
|
|
"no `trigger`/`action`/`sequence` block — blueprint can't fire"
|
|
)
|
|
|
|
return issues
|
|
|
|
|
|
def main() -> int:
|
|
root = Path(__file__).resolve().parent.parent
|
|
files = sorted(glob.glob(str(root / "examples" / "ha-blueprints" / "*.yaml")))
|
|
if not files:
|
|
print("ERROR: no blueprint YAML files found", file=sys.stderr)
|
|
return 2
|
|
|
|
fails = 0
|
|
for f in files:
|
|
issues = validate(Path(f))
|
|
rel = Path(f).relative_to(root)
|
|
if issues:
|
|
fails += 1
|
|
print(f"FAIL {rel}")
|
|
for i in issues:
|
|
print(f" {i}")
|
|
else:
|
|
print(f"ok {rel}")
|
|
|
|
if fails:
|
|
print(f"\n{fails} blueprint(s) failed validation", file=sys.stderr)
|
|
return 1
|
|
print(f"\nAll {len(files)} HA Blueprints validate OK")
|
|
return 0
|
|
|
|
|
|
if __name__ == "__main__":
|
|
sys.exit(main())
|