ha skill

2026-05-16 10:43:42 +02:00
parent 648184da43
commit 4f1f11d429
20 changed files with 906 additions and 694 deletions
@@ -0,0 +1,51 @@
+# Accès et preuves
+
+## Principe
+
+Toujours choisir l'accès le moins intrusif qui permet de répondre correctement.
+
+## Ordre de préférence
+
+1. **Artefacts locaux fournis par l'utilisateur**
+   - `home-assistant.log`
+   - `configuration.yaml` et fichiers inclus
+   - exports ou captures de dashboards
+   - diagnostics téléchargés depuis une intégration
+   - sorties de commandes déjà collectées
+
+2. **API Home Assistant avec token longue durée**
+   - utile pour récupérer version, états, registres, services et diagnostics exposés
+   - préférer le token au mot de passe
+
+3. **SSH**
+   - utile seulement pour métriques hôte, journaux système, stockage, fichiers non exportés, commandes supervisor/core selon le type d'installation
+   - justifier pourquoi SSH est nécessaire avant de le demander
+   - si SSH est retenu, collecter au minimum : hôte, port, utilisateur, puis soit mot de passe soit chemin de clé privée
+   - préférer l'authentification par clé quand elle est disponible ; utiliser le mot de passe seulement si c'est le mode réellement fourni
+
+4. **MCP**
+   - optionnel, jamais requis par principe
+   - l'utiliser uniquement s'il existe déjà et apporte un accès structuré, traçable ou plus sûr qu'un accès ad hoc
+
+## Preuves minimales à réunir
+
+- version exacte de Home Assistant Core
+- date/heure de collecte
+- type d'installation si connu ; si le shell distant est isolé dans un add-on, corroborer avec l'API ou d'autres indices au lieu de conclure trop vite à `unknown`
+- sources de logs inspectées
+- liste des fichiers de configuration lus
+- provenance des métriques matériel
+- liste des dashboards inspectés
+- liste des entités réellement observées
+
+## Commandes ou données typiquement utiles
+
+Les commandes exactes dépendent du mode d'installation et ne doivent être proposées qu'après vérification documentaire compatible avec la version installée.
+
+Exemples de catégories de données utiles :
+- version de Home Assistant
+- CPU et mémoire
+- espace disque
+- extraits de logs autour des erreurs, selon la source officielle adaptée au mode d'installation
+- registres d'entités et d'appareils
+- contenu des dashboards YAML ou exports équivalents
@@ -0,0 +1,25 @@
+# Trace de changements et retour arrière
+
+## Principe
+
+Ne jamais supprimer une entité, un service, une automatisation, un script ou un élément de dashboard sans créer d'abord une trace permettant de revenir en arrière.
+
+## Avant toute suppression demandée par l'utilisateur
+
+Créer un dossier horodaté `rollback/YYYYMMDDTHHMMSSZ/` contenant, selon le cas :
+- une copie des fichiers YAML concernés ;
+- une copie des extraits `.storage` concernés si lisibles ;
+- un export ou inventaire des entités ciblées ;
+- un fichier `changes.md` décrivant :
+  - ce qui va être supprimé ;
+  - pourquoi ;
+  - les preuves ;
+  - les fichiers touchés ;
+  - la procédure de restauration.
+
+## Règles
+
+- Ne jamais mettre de secret dans `changes.md`.
+- Préférer une désactivation ou un retrait ciblé à une suppression large quand l'intention de l'utilisateur est ambiguë.
+- Après modification, produire un résumé avant/après.
+- Si la suppression concerne une entité ou une automatisation utilisée par un dashboard, signaler explicitement les dépendances avant exécution.
@@ -1,114 +0,0 @@
-# Erreurs Home Assistant fréquentes — Catalogue documenté
-
-## Intégrations
-
-### `Platform X not ready`
- **Cause** : Le service distant n'est pas encore accessible au démarrage de HA
- **Solution** : Ajouter `initial_state: false` ou augmenter `scan_interval`. Vérifier la connectivité réseau.
- **Doc** : https://www.home-assistant.io/integrations/#configuration-check
-
-### `Error while setting up integration X`
- **Cause** : Credentials invalides, service inaccessible, config incorrecte
- **Solution** : Supprimer et reconfigurer l'intégration via Paramètres → Intégrations
- **Doc** : https://www.home-assistant.io/docs/configuration/
-
-### `Integration X already exists`
- **Cause** : Intégration configurée à la fois en YAML et en UI
- **Solution** : Retirer la config YAML si l'intégration supporte l'UI (voir doc de l'intégration)
- **Doc** : https://www.home-assistant.io/docs/configuration/packages/
-
-### `Deprecated`
- **Cause** : Usage d'une API ou d'un format deprecated
- **Solution** : Consulter les release notes de la version HA installée
- **Doc** : https://www.home-assistant.io/blog/ (chercher la version concernée)
-
---
-
-## Entités
-
-### `unavailable`
- **Cause possible 1** : Appareil physique hors ligne
- **Cause possible 2** : Intégration en erreur
- **Cause possible 3** : Template invalide
- **Diagnostic** : Vérifier les logs pour le nom de l'entité
-
-### `unknown`
- **Cause** : L'entité existe mais n'a pas encore reçu de valeur (souvent au démarrage)
- **Normal** : Peut disparaître après quelques secondes/minutes
- **Problématique** : Si persiste, vérifier la config
-
-### Template error
-```
-Error rendering template: UndefinedError: 'sensor.xyz' is undefined
-```
- **Solution** : Utiliser `states('sensor.xyz')` au lieu de `states.sensor.xyz.state` (plus robuste)
- **Doc** : https://www.home-assistant.io/docs/configuration/templating/
-
---
-
-## Base de données / Recorder
-
-### `Database disk usage: X MB`
- **Cause** : Base de données SQLite trop volumineuse
- **Solution** : Configurer `recorder` avec `purge_keep_days` et exclure les entités à haute fréquence
-```yaml
-recorder:
-  purge_keep_days: 7
-  exclude:
-    entity_globs:
-      - sensor.*_signal_strength
-      - sensor.*_rssi
-```
- **Doc** : https://www.home-assistant.io/integrations/recorder/
-
---
-
-## Lovelace / Dashboards
-
-### Custom card non chargée
-```
-Custom element doesn't exist: custom-card-name
-```
- **Cause** : La ressource custom card n'est pas déclarée ou le fichier est manquant
- **Solution** : Paramètres → Tableaux de bord → Ressources → Ajouter le JS
- **Doc** : https://www.home-assistant.io/dashboards/dashboards/
-
-### Entité manquante dans dashboard
-```
-Entity not available: sensor.xyz
-```
- **Solution** : Vérifier que l'entité existe (`États` dans les outils de développement), corriger le nom dans la carte
-
---
-
-## Réseau / SSL
-
-### `SSL CERTIFICATE_VERIFY_FAILED`
- **Cause** : Certificat auto-signé ou expiré
- **Solution** : Vérifier `verify_ssl: false` pour les connexions internes (non recommandé en prod), ou renouveler le certificat
- **Doc** : https://www.home-assistant.io/docs/configuration/securing/
-
-### `Connection refused` / `Cannot connect to host`
- **Cause** : Service distant éteint ou port bloqué par firewall
- **Diagnostic** : `ping`, `telnet HOST PORT` depuis le host HA
-
---
-
-## YAML / Configuration
-
-### Indentation YAML incorrecte
- **Erreur** : `mapping values are not allowed here`
- **Outil** : https://yaml-online-parser.appspot.com/
- **Conseil** : Utiliser 2 espaces, jamais de tabulations
-
-### `!secret not found`
- **Cause** : La clé référencée n'existe pas dans `secrets.yaml`
- **Solution** : Ajouter la clé dans `/config/secrets.yaml`
-
-### Config check
-```bash
-# HA OS
-ha core check
-# Docker
-docker exec homeassistant python -m homeassistant --config /config --script check_config
-```
@@ -0,0 +1,45 @@
+# Analyse des logs
+
+## Collecte
+
+- Conserver la source brute quand elle existe.
+- Si `rtk` est disponible localement, produire en complément une version compacte avec `rtk log` pour réduire le volume transmis au modèle.
+- Ne jamais remplacer la source brute par le résumé compact.
+
+## Stratégie selon le type d'installation
+
+### Home Assistant OS
+- Ne pas attendre de fichier `/config/home-assistant.log` par défaut.
+- Si un fichier dupliqué existe et n'est pas vide, le préférer pour la collecte automatisée car il évite un shell interactif et garde le flux brut disponible.
+- Considérer comme sources officielles prioritaires :
+  1. l'interface `Settings > System > Logs` ;
+  2. `ha core logs` depuis l'add-on officiel `Terminal & SSH` si l'accès SSH autorisé le permet ;
+  3. `/config/home-assistant.log` seulement si le mode `duplicate-log-file` a été activé volontairement.
+- Si plusieurs add-ons SSH sont installés, ne pas supposer qu'ils donnent le même accès : tracer l'add-on réellement utilisé pour la collecte.
+- Si `ha core logs` retourne `401 Unauthorized` en commande distante directe mais fonctionne en session ouverte, tester une session SSH interactive avec TTY (`ssh -tt`) : certains environnements d'add-on initialisent l'accès Supervisor seulement dans ce contexte.
+
+### Home Assistant Container / Core
+- Vérifier les fichiers logs de configuration quand ils existent et les commandes adaptées au mode d'installation.
+
+## Cas où aucune source de log exploitable n'est disponible
+
+Vérifier séparément :
+1. le type d'installation ;
+2. les sources officiellement attendues pour ce type ;
+3. l'existence éventuelle de fichiers dupliqués ;
+4. les erreurs d'autorisation éventuelles sur les commandes documentées.
+
+Si aucune source exploitable n'est accessible :
+- l'écrire explicitement dans `repair.md` ;
+- demander un export des logs depuis l'interface Home Assistant ou une source équivalente fournie par l'utilisateur ;
+- ne pas conclure à l'absence d'erreurs runtime.
+
+## Usage de `rtk`
+
+Exemple local :
+
+```bash
+rtk log home-assistant.log > home-assistant.compact.log
+```
+
+Le résumé compact sert à l'analyse rapide ; les constats importants doivent rester traçables vers le log brut.
@@ -0,0 +1,33 @@
+# Politique de documentation officielle
+
+## Règle principale
+
+Ne recommander une correction que si elle est soutenue par une documentation officielle Home Assistant compatible avec la version réellement installée.
+
+## Sources acceptables
+
+Privilégier, selon le sujet :
+- la documentation officielle Home Assistant ;
+- les notes de version officielles ;
+- la documentation développeur officielle Home Assistant ;
+- les pages officielles d'intégration Home Assistant.
+
+Les forums, blogs, dépôts personnels et réponses communautaires peuvent servir d'indices, jamais de preuve finale pour une correction.
+
+## Méthode de validation
+
+Pour chaque recommandation :
+1. noter la version installée ;
+2. vérifier que la fonctionnalité ou le paramètre existe pour cette version ;
+3. citer la source officielle consultée ;
+4. indiquer si la recommandation est :
+   - confirmée ;
+   - probable mais à vérifier ;
+   - non démontrée faute de documentation officielle.
+
+## Si la documentation manque
+
+Écrire explicitement qu'aucune correction certaine n'est proposée sans documentation officielle compatible. Donner seulement :
+- les faits observés ;
+- les vérifications complémentaires possibles ;
+- les informations à collecter pour lever l'incertitude.
@@ -0,0 +1,42 @@
+# Mise à jour du skill
+
+## Objectif
+
+Mettre à jour `ha-log-investigator` lorsqu'une évolution officielle de Home Assistant modifie la manière correcte de collecter les preuves, d'interroger l'API, de lire les logs, de traiter les dashboards, les réparations ou les fichiers de configuration.
+
+## Déclencheurs
+
+Lancer ce workflow si :
+- une documentation officielle contredit le comportement actuel du skill ;
+- une commande documentée change ;
+- une API officielle évolue ;
+- un mode d'installation modifie ses chemins ou ses sources de logs ;
+- un test réel révèle une hypothèse devenue obsolète.
+
+## Workflow de mise à jour
+
+1. Identifier l'évolution constatée.
+2. Vérifier l'information dans une source officielle Home Assistant.
+3. Décrire l'écart entre :
+   - comportement actuel du skill ;
+   - comportement officiel attendu.
+4. Mettre à jour uniquement les fichiers nécessaires :
+   - `SKILL.md`
+   - références concernées
+   - scripts concernés
+   - templates concernés
+5. Ajouter une entrée dans `history.md` avec :
+   - date ;
+   - évolution observée ;
+   - source officielle ;
+   - fichiers modifiés ;
+   - conséquence pratique.
+6. Revalider le skill.
+7. Si possible, retester sur un cas réel ou un artefact réaliste.
+
+## Règles
+
+- Ne jamais supprimer l'historique existant.
+- Ne pas mettre à jour le skill sur la base d'un forum, d'un blog ou d'une intuition seule.
+- Si une évolution est suspectée mais non confirmée officiellement, l'ajouter dans la section `À surveiller` de `history.md` au lieu de modifier le comportement du skill.
+- Conserver la compatibilité avec les versions anciennes seulement si elle est encore utile et documentée.
@@ -0,0 +1,35 @@
+# Spook
+
+## Rôle
+
+Utiliser Spook lorsqu'il est installé comme complément pour la gestion des réparations Home Assistant.
+
+Spook fournit des actions et entités autour du dashboard Repairs :
+- créer des issues ;
+- ignorer / réactiver des issues ;
+- compter les issues actives, ignorées et totales ;
+- suivre des problèmes récurrents dans un format visible dans Home Assistant.
+
+## Règles d'usage
+
+- Vérifier si Spook est installé avant de s'y fier.
+- L'utiliser comme outil de suivi et d'annotation des problèmes, pas comme source unique de vérité.
+- Croiser les issues Spook avec :
+  - les logs runtime ;
+  - l'état réel des entités ;
+  - Watchman ;
+  - la configuration YAML ;
+  - les réparations natives Home Assistant.
+
+## Quand l'utiliser
+
+- Quand tu veux matérialiser un problème récurrent dans Repairs.
+- Quand tu veux suivre l'état "à traiter / traité" pendant un nettoyage progressif.
+- Quand tu veux signaler une anomalie de façon visible dans Home Assistant sans modifier la logique métier.
+
+## Ce qu'il faut retenir
+
+- Spook est utile pour le pilotage du flux de corrections.
+- Spook ne remplace pas Watchman.
+- Spook ne remplace pas l'analyse des logs.
+- Spook ne remplace pas la correction de la cause racine.
@@ -0,0 +1,55 @@
+# Collecteur SSH
+
+Utiliser `scripts/collect_ssh_evidence.sh` lorsque SSH est justifié et que l'utilisateur veut une collecte reproductible en lecture seule.
+
+## Entrées attendues
+
+Un fichier d'identifiants au format `credentials.env` contenant au minimum :
+- `HA_SSH_HOST`
+- `HA_SSH_PORT`
+- `HA_SSH_USER`
+- soit `HA_SSH_PASSWORD`, soit `HA_SSH_KEY_PATH`
+
+Préférer `HA_SSH_KEY_PATH` si disponible.
+
+## Exemple
+
+```bash
+scripts/collect_ssh_evidence.sh \
+  --credentials ~/.ha-log-investigator/credentials.env \
+  --output ./ha-evidence
+```
+
+## Garanties
+
+- collecte en lecture seule ;
+- aucune modification distante ;
+- sorties regroupées dans un dossier horodaté ;
+- absence de secrets dans les rapports générés par le script.
+
+## Données collectées
+
+- système : `uname`, OS, CPU, mémoire, swap, disques ;
+- indices de version Home Assistant accessibles localement ;
+- extrait de logs Home Assistant ;
+- fichiers YAML principaux si accessibles ;
+- index des fichiers `.storage` si accessible.
+
+## Limites
+
+- les chemins varient selon le mode d'installation ;
+- l'authentification par mot de passe exige `sshpass` côté machine cliente ;
+- le script collecte des preuves, il ne remplace pas la validation par documentation officielle avant recommandation.
+
+
+## Plusieurs add-ons SSH
+
+Sur Home Assistant OS, préférer l'add-on officiel `Terminal & SSH` lorsqu'il faut collecter `ha core logs`.
+Si un autre add-on SSH est utilisé pour d'autres tâches, conserver des profils d'accès distincts et consigner lequel a servi à chaque collecte.
+
+
+## Cas `ha core logs` interactif uniquement
+
+Si `ha core logs` fonctionne après connexion interactive mais renvoie `401 Unauthorized` lorsqu'il est exécuté directement via `ssh host 'ha core logs'`, utiliser un mode interactif avec TTY pour la collecte des logs, puis nettoyer les séquences ANSI et le banner avant analyse.
+
+Cette situation doit être notée dans `repair.md` comme une contrainte d'accès, pas comme une erreur Home Assistant.
@@ -0,0 +1,40 @@
+# Watchman
+
+## Rôle
+
+Utiliser Watchman lorsqu'il est installé pour compléter l'audit Home Assistant.
+
+Watchman scanne les fichiers de configuration et signale les entités et actions/services référencés mais manquants ou indisponibles. Il produit un rapport texte, généralement `watchman_report.txt`, et peut aussi retourner un rapport via l'action `watchman.report`.
+
+## Règles d'usage
+
+- Vérifier si Watchman est installé avant l'analyse finale.
+- S'il est installé, lire le rapport le plus récent et l'intégrer aux constats.
+- Ne pas traiter automatiquement chaque ligne Watchman comme une vérité absolue : Watchman utilise une analyse heuristique et peut produire des faux positifs ou faux négatifs.
+- Croiser ses résultats avec :
+  - l'état réel des entités ;
+  - les dashboards ;
+  - les automatisations ;
+  - les logs runtime.
+
+## Rapport attendu
+
+Chercher en priorité :
+- `/config/watchman_report.txt`
+- ou le chemin configuré dans Watchman si différent.
+
+## Quand produire le rapport
+
+Si nécessaire et si l'utilisateur autorise l'action, exécuter `watchman.report` depuis Home Assistant avec création de fichier afin d'obtenir un rapport actualisé avant l'analyse finale.
+
+## Ce qu'il faut reprendre dans les livrables
+
+Dans `repair.md` :
+- nombre d'entités manquantes ;
+- nombre d'actions/services manquants ;
+- exemples significatifs ;
+- indication que le rapport vient de Watchman.
+
+Dans `best_entity.md` :
+- pistes de nettoyage des références orphelines ;
+- priorités d'amélioration si elles sont confirmées par d'autres sources.