Aller au contenu

Diagnostic d'installation (coach-doctor)

/coach-doctor (ou python3 scripts/coach_doctor.py directement) vérifie l'installation en une commande, sans rien écrire — et, par défaut, sans appeler Garmin Connect (voir --probe-mcp plus bas).

Lancer

python3 scripts/coach_doctor.py
coach doctor — /chemin/vers/votre/workspace
❌ garmin_token           Tokens Garmin expirés depuis 3 jour(s) (/home/alex/.garminconnect).
    → correctif : uv run garmin-mcp-auth
✅ garmin_mcp             MCP garmin : commande « garmin-mcp » présente (/home/alex/.local/bin/garmin-mcp).
✅ config_files           Configuration TOML valide (config/workspace.toml, config/workspace.user.toml).
✅ athlete_profile        FC max et FC de repos renseignées dans le profil.
✅ index_freshness        Index .arc/coach.db à jour.
✅ out_of_contract        Aucun fichier hors contrat.
ℹ️ daily_sync_scheduled   Aucun LaunchAgent daily-sync — synchronisation Garmin manuelle uniquement.
    → correctif : ./install.sh --daily-sync
⚠️ ntfy_configured        ntfy activé mais aucun topic configuré.
    → correctif : scripts/setup-ntfy.sh

Au moins une vérification est en échec (❌) — voir les correctifs ci-dessus.

(Le chemin affiché est toujours le chemin ABSOLU résolu — ~/.garminconnect n'apparaît jamais littéralement en sortie.)

Ce qui est vérifié

Vérification Détail Sévérité
garmin_token Âge/échéance des tokens Garmin (~/.garminconnect par défaut) ⚠️ à moins de 14 jours de l'échéance, ❌ si expirés ou absents
garmin_token_perms (source garmin, sinon ℹ️) Droits de ~/.garminconnect (ou du dossier résolu) et de ~/.garminconnect_base64 : dossier et fichiers de jetons inaccessibles au groupe/autres. Seuls les droits sont lus, jamais le contenu. Corrige : chmod 700 ~/.garminconnect && find ~/.garminconnect -type f -exec chmod 600 {} + (ou relancer ./install.sh) — GHSA-wjhr-76vg-2hvc ⚠️ si lisibles par d'autres comptes, ℹ️ si aucun dossier de jetons
garmin_mcp Présence/exécutabilité du binaire MCP garmin (aucun process lancé) ❌ si la commande est introuvable ou non exécutable
garmin_mcp_pin (source garmin, sinon ℹ️) Serveur garmin-mcp installé par uv tool au commit épinglé par install.sh (GARMIN_MCP_REF) ? Lu dans le direct_url.json (dist-info garmin_mcp-*), aucun réseau. La réinstallation au pin met à jour les dépendances transitives (correctifs de sécurité) et conserve les jetons ⚠️ si le commit diffère du pin, ℹ️ pour une origine personnalisée ou illisible
strava_connection (#164, source strava seulement, sinon ℹ️) Node.js 18+, wrapper, serveur strava déclaré, jetons présents et non lisibles par d'autres — valeurs jamais lues ni affichées, aucun appel réseau ❌ si Node.js/wrapper/serveur/jeton de rafraîchissement manquent, ⚠️ si identifiants client absents ou fichier lisible par d'autres
coros_connection (--coros seulement, sinon ℹ️) relais déclaré, pas masqué par un serveur coros ajouté à la main, jetons du projet avec jeton de rafraîchissement, droits 700/600 — valeurs jamais lues ni affichées ; --probe-mcp pour un appel réel ❌ si relais absent ou compte non connecté (arc_coros_auth.py login), ⚠️ si une entrée manuelle masque le relais ou si les jetons sont lisibles par d'autres
openwearables (#220, [health].source = "openwearables" seulement, sinon ℹ️) Fournisseur valide, adresse, fichier de clé d'API présent et en mode 600 (valeur jamais lue ni affichée). Puis, automatiquement, un seul appel à l'instance via arc_openwearables.py check (3 s par requête, sous-processus plafonné à 12 s ; --no-probe-ow pour rester hors ligne) ❌ configuration incomplète, clé absente ou lisible par d'autres, fournisseur garmin/strava/inconnu, instance injoignable, clé refusée (401) ; ⚠️ fabricant non actif, synchro périmée, version non testée, plusieurs utilisateurs sans user_id
config_files config/workspace.toml et config/workspace.user.toml sont du TOML valide ❌ si absent ou invalide, ⚠️ si validation stricte indisponible (Python < 3.11)
athlete_profile FC max / FC de repos renseignées dans planning/Runner_Profile.md ℹ️ sinon — le coach utilise le RPE à la place
index_freshness .arc/coach.db à jour par rapport aux fichiers du workspace (y compris les fichiers supprimés) ⚠️ si périmé ou si un fichier supprimé est encore indexé, ℹ️ si jamais construit
out_of_contract Nombre de fichiers sans bloc ```arc conforme ⚠️ si non nul
daily_sync_scheduled Tâche cron (Linux) ou LaunchAgent (macOS) du daily-sync ; en mode watch, dernier passage de scripts/watch.py ℹ️ si non installé (choix valide) ; ⚠️ si le watcher est installé mais muet depuis plus de 3 intervalles
ntfy_configured Notifications push configurées, si activées ℹ️ si désactivées, ⚠️ si mal configurées
gear_sync Synchronisation du matériel Garmin (#133) : la liste blanche GARMIN_ENABLED_TOOLS de .mcp.json contient get_gear et get_activity_gear, et les paires actives du profil portent un segment garmin: <uuid>. Statique — le doctor n'appelle jamais Garmin ; lister le matériel Garmin sans puce est fait par le coach (get_gear) ⚠️ si la liste blanche est antérieure à #133 (relancer ./install.sh), ℹ️ si des paires actives ne sont pas associées (ou liste blanche illisible en mode passerelle), ℹ️ sous la source intervals.icu
weight_sync Poids lu dans Garmin Connect (#222) : la liste blanche GARMIN_ENABLED_TOOLS contient get_daily_weigh_ins et get_weigh_ins (lecture seule). Statique — aucun appel Garmin ℹ️ si la liste blanche est antérieure à #222 (relancer ./install.sh ; en mode passerelle, éditer leanproxy_servers.yaml), ℹ️ sous une source autre que Garmin — jamais un avertissement : le poids reste déclaratif
gear_history (#145) Historique sans matériel : au moins 5 séances avec garmin_activity_id, dont plus de la moitié sans gear_id (ℹ️, jamais ⚠️) — propose python3 scripts/garmin_gear_backfill.py (simulation). Statique : aucun appel Garmin.
fit_reader fitparse présent dans l'environnement MCP de la source (garmin-mcp ou intervals-icu-mcp), pour lire les FIT téléchargés ⚠️ si absent : zones, GAP, VAM… restent vides — relancer ./install.sh --source <source>
intervals_mcp_pin (#165) Serveur intervals-icu-mcp installé par uv tool au commit épinglé par install.sh ? Lu dans le direct_url.json de son environnement — aucun réseau. Sans objet hors [data].source = "intervals" ⚠️ si installé depuis l'ancien dépôt eddmann (outils sans préfixe icu_) — ./install.sh --source intervals puis nouvelle session ; ℹ️ si commit différent du pin, origine personnalisée ou illisible
telegram (#174, [telegram].enabled seulement, sinon ℹ️) Liste blanche allowed_chat_ids non vide, fichier du jeton présent en mode 600 avec un TELEGRAM_BOT_TOKEN au bon format (valeur jamais affichée), jeton non exporté dans l'environnement, chat_bridge cohérent avec [chat], service vivant (battement .arc/telegram/heartbeat de moins de 5 min). Aucun appel réseau ⚠️ au plus (un bot arrêté est une perte de confort), jamais ❌
telegram_chat (#337, expérimental ; ℹ️ tant que scripts/coach-telegram-chat.sh install n'a pas été lancé) Binaires claude, bun et tmux, plugin Telegram configuré (~/.claude/channels/telegram/.env), politique d'accès allowlist avec au moins un compte autorisé, jeton du plugin différent de celui de [telegram].token_file (deux processus en long polling sur le même bot : erreur 409), session tmux coach-telegram-chat vivante. Aucun jeton affiché, aucun appel réseau ⚠️ au plus, jamais ❌
family_registry, family_tokens, family_ntfy, family_sync (#127, seulement si le registre family.toml est donné explicitement — --family ou ARC_FAMILY, jamais découvert tout seul ; jamais avec --check ni sous ARC_LOCK_WORKSPACE=1, pour ne pas décrire les autres membres depuis le chat d'un membre) Registre valide ; aucun dossier de jetons Garmin partagé entre deux membres ; un topic ntfy par membre ; une synchronisation planifiée par membre. Voir Mode famille. Aucun appel réseau ❌ si le registre est invalide ; ⚠️ si des jetons ou un topic sont partagés ; ℹ️ si la synchronisation d'un membre n'est pas détectée

Un ❌ fait échouer la commande (code de sortie non nul). Un ⚠️ ou un ℹ️ jamais — ce sont des dégradations connues, pas des pannes.

garmin_mcp : présence par défaut, handshake réel en option

Lancer réellement garmin-mcp déclenche une connexion à Garmin Connect avant même de répondre au protocole MCP (voir la docstring de check_garmin_mcp_presence dans scripts/coach_doctor.py) : réseau, retries, et une possible réécriture des tokens. coach doctor s'en tient donc par défaut à vérifier que le binaire configuré existe et est exécutable.

Le contrôle llm_config reprend python3 scripts/arc_llm.py check (#268) : cohérence runner / backend / modèle / clé, puis jeton d'abonnement ChatGPT / Copilot dans le magasin du coach, OPENCODE_DISABLE_DEFAULT_PLUGINS. Il reste statique (aucun appel réseau) ; --probe-llm ajoute l'appel minimal au fournisseur (clé OpenRouter valide, crédit, quota gratuit du jour, liste des modèles Anthropic / compatible OpenAI) et ne fait jamais plus qu'un avertissement. Détail et actions : Dépannage — La connexion IA.

Un vrai handshake MCP initialize, borné dans le temps, reste disponible :

python3 scripts/coach_doctor.py --probe-mcp   # CONTACTE Garmin Connect

Le contrôle openwearables (#220) fait, lui, un appel d'office quand la configuration est complète : à l'instance Open Wearables de l'athlète, jamais à un tiers (un seul arc_openwearables.py check, 3 s par requête, sous-processus plafonné à 12 s). --no-probe-ow le garde hors ligne.

Méthode de détection de l'échéance des tokens

Le client garminconnect vendored par garmin-mcp ne lit/écrit qu'un seul fichier : garmin_tokens.json — c'est donc TOUJOURS lui qui fait foi quand il est présent, même si un oauth2_token.json (format garth, jamais produit par cette installation) traîne encore d'une ancienne configuration.

  1. garmin_tokens.json (le fichier réel) ne contient aucune échéance longue durée exploitable : son di_token est un JWT dont le claim exp correspond à une session courte (régénérée automatiquement, ~1 jour), et di_refresh_token n'est pas un JWT. Repli : date de dernière modification du fichier + une fenêtre de validité d'environ 6 mois — voir Dépannage. Limite connue : ce fichier est réécrit à chaque rafraîchissement automatique du token, ce qui repousse la mtime (donc l'échéance estimée) sans que la session ait réellement été renouvelée pour 6 mois de plus — ne traitez pas mtime_fallback comme une garantie, seulement comme la meilleure estimation disponible.
  2. oauth2_token.json (format garth) n'est utilisé QUE si garmin_tokens.json est absent : son champ explicite refresh_token_expires_at sert alors de signal.

Aucun contenu de token n'est jamais affiché : seuls des métadonnées (chemin, date d'échéance, nombre de jours restants) apparaissent en sortie.

Sortie machine

python3 scripts/coach_doctor.py --json
python3 scripts/coach_doctor.py --json --check garmin_token   # une seule vérification (#32)

Un objet par vérification (id, status, message, fix), plus expires_at/days_left/source pour garmin_token — schéma complet en tête de scripts/coach_doctor.py. Conçue pour être réutilisée telle quelle par l'alerte ntfy avant expiration des tokens (#32).

Options utiles

python3 scripts/coach_doctor.py --workspace /chemin/vers/le/workspace
python3 scripts/coach_doctor.py --tokens-dir /chemin/de/test     # override du répertoire de tokens
python3 scripts/coach_doctor.py --now 2026-09-24T12:00:00+00:00  # horloge figée (tests)
python3 scripts/coach_doctor.py --check garmin_token             # une seule vérification, sans MCP
python3 scripts/coach_doctor.py --probe-mcp                      # handshake MCP réel (contacte Garmin)
python3 scripts/coach_doctor.py --probe-llm                      # connexion IA : appel réseau minimal vers le fournisseur (#268)
python3 scripts/coach_doctor.py --check openwearables --no-probe-ow # Open Wearables sans appel réseau (#220)

Quand le lancer

  • Avant toute autre investigation : synchronisation en échec, erreur MCP, agent qui semble se comporter bizarrement.
  • Après une réinstallation ou un changement de machine.
  • Périodiquement, en curiosité — par défaut, il ne modifie rien et ne contacte personne.