Makigawa
Interface mobile personnelle posée au-dessus d’intervals.icu : un plan
d’entraînement de deux semaines qui se corrige tout seul, sans ouvrir le site
web. Construite comme une PWA installable — une app web qui s’ajoute à
l’écran d’accueil d’Android et se comporte comme une app native.
Voir CLAUDE.md pour le contexte, les règles métier et les contraintes, et
docs/section-5-regles-adaptation.md pour la spécification qui fait foi.
L’app ne fait que lire. Garmin verse les activités dans intervals.icu,
intervals.icu calcule la charge, la forme et la fatigue, Makigawa lit tout cela
et en déduit ce qu’il y a à faire les quatorze jours qui viennent. Elle n’écrit
rien dans le calendrier — la seule exception est la suppression d’un événement,
derrière un appui long de deux secondes.
Ce qu’elle sait faire :
- Tenir un plan de deux semaines et le replacer à chaque lecture — la
question centrale étant, séance par séance, « aujourd’hui est-il un bon jour
pour celle-ci ? »
- Composer les séances elle-même, sur des motifs relevés chez l’athlète, en
pourcentage de FTP et jamais en watts.
- Doser la progression : un niveau par zone, lu sur ce qui a été tenu, et
un plafond de +10 % de forme par semaine au-delà duquel elle n’ajoute rien.
- Compter les trajets domicile-travail, qui portent l’essentiel de la
charge hebdomadaire et se marquent d’avance dans le calendrier.
Local-first : ce que l’athlète choisit — sa marque de trajet, un refus, une
décharge acceptée — reste dans le stockage du navigateur, sur le téléphone. Pas
de compte, pas de serveur, pas de synchronisation. Corollaire à garder en tête :
effacer les données du site depuis Chrome efface ces choix ; les activités et le
calendrier, eux, vivent dans intervals.icu et se relisent.
La page porte une balise noindex : elle n’est pas indexée par les moteurs de
recherche. Un robots.txt ne conviendrait pas ici, il n’est lu qu’à la racine
du domaine, qui dépend d’un autre dépôt.
Installer sur le téléphone
- Ouvrir https://tvsgit-dev.github.io/Makigawa/ dans Chrome sur Android.
- Chrome propose l’installation (bannière, ou bouton « Installer sur l’écran
d’accueil » dans l’app). Sinon : menu ⋮ → Ajouter à l’écran d’accueil.
- Lancer Makigawa depuis l’écran d’accueil. Le bloc Ce téléphone, en bas de
l’écran, doit afficher App installée, Hors-ligne : prêt et HTTPS.
Saisir ensuite l’identifiant athlète et la clé API intervals.icu, puis
Tester la connexion. Les identifiants restent dans le stockage local du
téléphone et ne sont envoyés qu’à intervals.icu.
Pour vérifier le mode hors-ligne : activer le mode avion, puis relancer l’app
depuis l’écran d’accueil. Elle doit démarrer normalement.
Développement
npm install
npm run dev # serveur local, service worker actif
npm run build # vérification des types + build de production dans dist/
npm run preview # sert dist/ comme en production
npm run typecheck # types seuls
npm run icons # régénère les icônes PNG depuis scripts/generate-icons.mjs
npm run dev écoute sur toutes les interfaces (--host) : depuis un téléphone
sur le même réseau Wi-Fi, l’URL est http://<ip-de-la-machine>:5173/Makigawa/.
Attention, en HTTP simple le navigateur bloque le GPS et le service worker —
seul le site déployé en HTTPS permet de tout tester.
Déploiement
Chaque push sur main ou claude/mobile-execution-m4j7mk déclenche
.github/workflows/deploy.yml, qui construit le site et le publie sur GitHub
Pages.
Réglage à faire une seule fois : dans Settings → Pages du dépôt, choisir
Source : GitHub Actions. Tant que ce n’est pas fait, le workflow échoue à
l’étape « Configurer Pages » — le jeton d’un workflow n’a pas le droit de créer
le site Pages lui-même, seul le propriétaire du dépôt peut l’activer.
Deux contraintes propres aux dépôts privés :
- Publier des Pages depuis un dépôt privé demande un plan GitHub Pro (ou
Team / Enterprise). Sur un compte gratuit, l’option n’est disponible que pour
les dépôts publics.
- Même avec Pro, le site publié est accessible publiquement ; seul le code
reste privé. Restreindre l’accès au site demande GitHub Enterprise.
Si aucune des deux ne convient, les alternatives qui déploient un dépôt privé
sans le rendre public sont Vercel, Netlify et Cloudflare Pages (niveaux
gratuits) : il suffit alors de remplacer ce workflow et de construire avec
VITE_BASE=/.
L’horodatage du build est affiché en haut de l’app : il permet de confirmer d’un
coup d’œil que le téléphone a bien reçu la dernière version. Quand une nouvelle
version est déployée, l’app affiche une bannière « Mettre à jour » plutôt que de
se recharger toute seule — utile pour ne pas perdre l’écran en pleine sortie.
Chemin de base
Le site est servi sous /Makigawa/, d’où base: '/Makigawa/' dans
vite.config.ts. Pour un domaine personnalisé ou un déploiement à la racine,
construire avec VITE_BASE=/ npm run build.
Structure
.github/workflows/deploy.yml Build + déploiement GitHub Pages
docs/ La spécification des règles, qui fait foi
scripts/generate-icons.mjs Génération des icônes PNG (sans dépendance)
public/ Icônes, favicon — copiés tels quels
src/api/ Lecture d’intervals.icu (et la seule suppression)
src/rules/ Le moteur : l’échelle de charge, la question du
E.2, la reprise, la décharge, la vitesse de montée
src/workouts/ Les familles de séances, leur composition, les
niveaux par zone, la routine de souplesse
src/storage/ Ce que le téléphone retient, et rien de plus
src/components/ L’interface
vite.config.ts Build + manifest de la PWA
Le moteur est une fonction pure : il ne connaît pas le réseau, ne touche à
rien, et produit des propositions. C’est ce qui le rend testable — 250 tests
environ, dont plusieurs gardent des décisions de fond plutôt que du code
(aucune intensité en watts, aucune charge inventée, aucune écriture depuis
l’interface).
