docs: roadmap v2 - lecture facilitee (sommaire, legende, quick wins, KPI), 12 axes enrichis (modeles locaux, lab, rapports, couts, favoris, profils), jalons versionnes

ROADMAP.md

@@ -0,0 +1,381 @@
+# 🗺️ ROADMAP agent-manager — vers le « super outil »
+
+> **Version du document : 2.0** · Statut : propositions, non engagées
+> Base : analyse du code **v0.2.7** (Rust, 45+ tests, zéro dépendance runtime)
+
+---
+
+## 📖 Sommaire
+
+1. [Résumé exécutif](#1--résumé-exécutif)
+2. [Légende de lecture](#2--légende-de-lecture)
+3. [Quick wins — valeur immédiate](#3--quick-wins--valeur-immédiate)
+4. [État des lieux](#4--état-des-lieux)
+5. [Vision & principes](#5--vision--principes)
+6. [Socle technique : le modèle de données](#6--socle-technique--le-modèle-de-données)
+7. [Les 12 axes](#7--les-12-axes)
+8. [Jalons versionnés](#8--jalons-versionnés)
+9. [Indicateurs de succès (KPI)](#9--indicateurs-de-succès-kpi)
+10. [Risques & garde-fous](#10--risques--garde-fous)
+11. [Par où commencer](#11--par-où-commencer)
+
+---
+
+## 1. 📌 Résumé exécutif
+
+**am** est aujourd'hui un excellent *gestionnaire* d'agents : 72 agents au
+catalogue, 9 méthodes d'installation, dépendances résolues automatiquement,
+processus pilotés, REPL avec passerelle shell, sauvegarde export/import.
+
+Mais il est **aveugle** : il ne retient ni ce qui a été fait, ni quand, ni
+par quel agent, ni dans quel projet, ni avec quel résultat. Les logs sont du
+texte libre non interrogeable, l'état ne contient que les installations et
+le PID courant, l'historique est un simple fichier plat.
+
+Cette roadmap transforme **am** en **cockpit de votre parc d'agents IA** :
+
+| Rôle | Promesse | Porté par |
+|---|---|---|
+| 📓 Journal de bord | tout est tracé, rien ne se perd | Axe 1 (journal d'événements) |
+| 🔎 Rétroviseur | tout est cherchable en 2 secondes | Axes 2, 3, 4 |
+| 📊 Tableau de bord | tout est mesuré | Axes 1, 5, 9 |
+| 🤖 Copilote | il pilote à votre place | Axes 6, 7 |
+
+**Chiffres clés :** 12 axes · ~55 fonctionnalités · 4 jalons (v0.3.0 → v1.0)
+· ~15 semaines de travail cumulé · 0 dépendance runtime ajoutée.
+
+---
+
+## 2. 📚 Légende de lecture
+
+| Symbole | Signification |
+|---|---|
+| **P0** | Fondations — à démarrer tout de suite (socle des autres axes) |
+| **P1** | Court terme — après la phase 0 |
+| **P2** | Moyen terme |
+| **P3** | Vision — long terme |
+| ⭐ | Reprend une demande explicite de l'utilisateur |
+| **S** | Effort : moins d'1 jour |
+| **M** | Effort : 2 à 4 jours |
+| **L** | Effort : 1 à 2 semaines |
+| **XL** | Effort : plus de 2 semaines |
+| ⬜ / 🔨 / ✅ | Proposé / En cours / Livré (rien n'est commencé aujourd'hui) |
+
+---
+
+## 3. ⚡ Quick wins — valeur immédiate
+
+*Tous en effort S, phase P0, sans dépendance sur le socle. Livrables en
+quelques jours, à caler avant ou pendant la construction du journal.*
+
+| Fonctionnalité | Commande | Apport |
+|---|---|---|
+| Voir les logs d'un agent | am logs claude-code (--follow) | tail des logs déjà écrits par process.rs |
+| Filtres sur la liste | am list --running · --sort name,version,status | repérage instantané |
+| Éditer la config sans éditeur | am config set key value | moins de friction YAML |
+| Alias à la volée | am alias add cc claude-code | sans éditer le fichier |
+| Historique propre | dédup + horodatage de history.txt | base saine pour l'axe 2 |
+| Doctor scriptable | am doctor --json | CI et monitoring |
+| Ouvrir l'installation | am open claude-code | explorer le répertoire de l'agent |
+| Version scriptable | am version --json | introspection des scripts |
+
+---
+
+## 4. 🧭 État des lieux (points d'ancrage dans le code)
+
+| Brique actuelle | Fichier | Limite aujourd'hui |
+|---|---|---|
+| Catalogue 72 agents, alias, groupes | src/catalog.rs, config.yaml | recherche = sous-chaîne stricte, pas de ranking |
+| Installation (9 méthodes), dépendances OS | src/installers/, src/deps.rs, src/toolchain.rs | solide — rien à redire |
+| État local | src/state.rs (state.json v1) | installations + PID courant uniquement, **aucun historique** |
+| Détection externe + cache | src/probe.rs | excellent pattern de cache — à généraliser |
+| Processus | src/process.rs | logs non structurés, pas de sessions, pas de métriques |
+| Journal applicatif | src/output.rs | texte libre horodaté, non interrogeable |
+| REPL + passerelle shell | src/repl.rs (history.txt, session_id()) | historique plat, pas de recherche ni de stats |
+| Backup | src/commands/export_import.rs | manuel, pas de synchronisation |
+
+---
+
+## 5. 🎯 Vision & principes directeurs
+
+**Vision :** le cockpit unique du parc d'agents — journal de bord, rétroviseur,
+tableau de bord et copilote.
+
+**Principes :**
+
+1. **Zéro dépendance runtime** — tout est Rust pur et fichiers locaux
+   (JSONL/JSON), jamais de base de données externe.
+2. **Local par défaut, opt-in pour le distant** — la télémétrie n'existe que
+   si l'utilisateur l'active ; tout le reste est 100 % local.
+3. **Contrats stables** — les sorties --json sont la base des scripts et des
+   futurs UI : champs ajoutés, jamais retirés.
+4. **Performance** — écriture en append (JSONL), lectures par fenêtres
+   temporelles, index dérivés régénérables, caches sur le modèle de probe.rs.
+5. **Livraison continue** — chaque phase produit un binaire utilisable et
+   testé ; la barre des 45+ tests monte à chaque jalon.
+
+---
+
+## 6. 🧱 Socle technique : le modèle de données
+
+*Tout dépend de ceci. À construire en premier, avant les commandes visibles.*
+
+    state_dir/
+      state.json            # v2 : + sessions_count, last_used (migration auto depuis v1)
+      events.jsonl          # NOUVEAU — journal d'événements (source de vérité)
+      events-202608.jsonl   # rotation mensuelle
+      sessions.json         # NOUVEAU — registre des sessions (index dérivé)
+      history/
+        <session>.jsonl     # NOUVEAU — historique structuré du REPL
+      projects.json         # NOUVEAU — agrégats par projet (recalculable)
+      probe-cache.json      # existant — pattern de cache à suivre
+
+| Fichier | Rôle | Alimenté par | Reconstruction |
+|---|---|---|---|
+| events.jsonl | faits bruts (start, stop, run, install…) | process.rs, run_cmd.rs, install_cmd.rs, repl.rs, doctor_cmd.rs | source de vérité, jamais reconstruit |
+| sessions.json | index des sessions | dérivé du journal | doctor --fix (rejoue le journal) |
+| projects.json | agrégats par projet | dérivé du journal | doctor --fix |
+| history/*.jsonl | commandes REPL | repl.rs | non (données primaires) |
+| state.json v2 | installations + résumé | state.rs | partiellement (compteurs depuis le journal) |
+
+**Règles :** JSONL append-only pour les faits · JSON dérivés régénérables ·
+migration additive (state v1 reste lisible partout) · doctor --fix répare
+tout ce qui peut l'être.
+
+---
+
+## 7. 🗂️ Les 12 axes
+
+### Axe 1 — 📊 Observabilité & statistiques d'utilisation ⭐
+
+🎯 Savoir **quoi** a tourné, **quand**, **combien de temps**, avec **quel
+taux de succès** — et **combien ça coûte**.
+
+| Fonctionnalité | Effort | Phase |
+|---|---|---|
+| Journal d'événements events.jsonl (toutes les actions de am) | M | P0 |
+| am stats + --period 7d/30d/90d + --json (tableaux et barres ASCII) | M | P0 |
+| am top — classement des agents par utilisation | S | P1 |
+| am log — filtres agent/type/date, --follow | S → M | P0 → P1 |
+| am report — rapport hebdo/mensuel en markdown (top agents, échecs, changements) | M | P1 |
+| Suivi des coûts — tokens/€ par session quand l'agent expose son usage (Claude Code --output-format json, Codex…) | M | P2 |
+| am monitor — TUI temps réel : CPU/mémoire par PID, uptime, alertes | L | P2 |
+| Télémétrie anonyme **opt-in** (compteurs agrégés uniquement, jamais de chemins) | M | P3 |
+
+    am stats                    # vue globale
+    am stats claude-code --period 30d
+    am top                      # qui tourne le plus
+    am report --last-week       # digest markdown
+
+### Axe 2 — 💾 Historique des commandes ⭐
+
+🎯 Gérer, **rechercher** et **réutiliser** tout ce qui a été tapé.
+
+| Fonctionnalité | Effort | Phase |
+|---|---|---|
+| Historique structuré : history/<session>.jsonl (cmd, kind am/shell, cwd, durée, exit, agent) + migration de history.txt | M | P0 |
+| am history — filtres --kind, --cwd, --search, --failed, --session | M | P0 |
+| Ctrl-R + !! + !install + !42 + ^old^new dans le REPL | M | P1 |
+| am history --rerun 42 (réexécution confirmée) | S | P1 |
+| Playbooks : am history 12..25 --save deploy.yaml puis am playbook deploy.yaml | L | P2 |
+
+    am history --search "install" --failed
+    am history --rerun 42
+
+### Axe 3 — 🧭 Projets & workspaces ⭐
+
+🎯 Centraliser **quel agent travaille sur quel projet** — automatiquement.
+
+| Fonctionnalité | Effort | Phase |
+|---|---|---|
+| Contexte auto au lancement : racine + branche git, stack détectée (Cargo.toml, package.json…), mis en cache | S | P0 |
+| am projects / am projects api — agents, sessions, durées, dernière activité | M | P1 |
+| Profils de projet dans config : default_agent, env, hooks | M | P1 |
+| am start (sans argument) = agent par défaut du dossier courant ; REPL contextuel | S | P1 |
+| am init — génère un agent-manager.yaml selon la stack détectée | S → M | P0 |
+| Templates : am init --template web | M | P2 |
+
+    am projects
+    am projects api
+    am init            # dans un projet Node → config pré-remplie
+
+### Axe 4 — 🗂️ Sessions centralisées ⭐
+
+🎯 Un registre unique de **toutes les sessions de tous les agents** —
+consultable, reprenable, archivable.
+
+| Fonctionnalité | Effort | Phase |
+|---|---|---|
+| sessions.json + session_id() partagé (repl.rs) ; fin de session avec exit code et durée | M | P0 |
+| Réconciliation au démarrage : sessions interrompues (crash, reboot) marquées et datées | S | P0 |
+| am sessions — filtres agent/projet/statut ; show = résumé + extrait de log | M | P0 |
+| am timeline — vue chronologique unifiée de toute l'activité | M | P1 |
+| am sessions resume <id> — relance avec les mêmes args/env/cwd | M | P1 |
+| am sessions export <id> + rétention configurable (settings.sessions_retention_days) | M | P2 |
+
+    am sessions --status failed
+    am sessions show 20260815_143926_a1b2c3
+    am timeline --project api
+
+### Axe 5 — 🖥️ Tableau de bord
+
+🎯 Voir l'état du parc d'un coup d'œil.
+
+| Fonctionnalité | Effort | Phase |
+|---|---|---|
+| am dashboard — TUI (ratatui/crossterm) : vue d'ensemble, activité en direct, stats, sessions, projets | L | P1 |
+| am web — serveur local + API JSON + page HTML embarquée avec graphiques | XL | P2 |
+
+### Axe 6 — 🤖 Automatisation & orchestration
+
+🎯 Laisser am **superviser et piloter seul** le parc.
+
+| Fonctionnalité | Effort | Phase |
+|---|---|---|
+| Hooks on_install / on_start / on_stop / on_update (agent, projet, global) — via le runner existant | M | P0 |
+| am watch claude-code --restart-on-crash --notify | M | P1 |
+| Services : unités systemd / plists launchd / tâches Windows, am service install claude-code --autostart | L | P2 |
+| Planification : am schedule --daily update --all + check santé (cron / Task Scheduler) | M | P2 |
+| Orchestration de groupes : ordre, --parallel, attente de santé | L | P2 |
+| Conteneurs : profil docker/podman par agent (isolation à la demande) | L | P2 |
+| am doctor --watch — vérifications périodiques avec alertes | M | P2 |
+
+### Axe 7 — 🧠 Intelligence & catalogue
+
+🎯 Trouver le bon agent, suivre leurs sorties, et comparer.
+
+| Fonctionnalité | Effort | Phase |
+|---|---|---|
+| Recherche fuzzy dans am search (typos, scoring, « vouliez-vous dire ») | M | P1 |
+| am compare a b — tableau côte à côte (méthode, deps, catégorie, activité) | S | P1 |
+| am news — dernières releases des agents installés (API GitHub/Gitea, cache) | M | P1 |
+| Catalogue distant : am catalog update / am catalog add <url> | M | P2 |
+| am suggest "un agent pour du Python" — tags + usage réel | M | P2 |
+| am lab — benchmark : même tâche sur N agents, comparaison durée/résultat/coût | L | P2 |
+| Registre communautaire : publier son catalogue (Gitea) + am registry | L | P3 |
+| am ask "installe claude et lance-le" — langage naturel → commande am (fournisseur LLM configurable, optionnel) | L | P3 |
+
+### Axe 8 — 🔒 Sécurité & gouvernance
+
+🎯 Protéger les secrets, tracer les changements, pouvoir revenir en arrière.
+
+| Fonctionnalité | Effort | Phase |
+|---|---|---|
+| am secret set OPENAI_KEY --agent claude-code (keyring OS) + injection --env automatique | M | P1 |
+| am audit — qui a modifié quoi quand (checksums des configs, événements) | M | P2 |
+| am update --rollback — backup automatique avant chaque mise à jour | M | P2 |
+| Politiques : pin de version, settings.update_policy | S | P2 |
+| Profils sandbox par agent (commandes/répertoires autorisés) | L | P3 |
+
+### Axe 9 — 🌐 Multi-machine & collaboration
+
+🎯 Retrouver son cockpit partout, et le partager.
+
+| Fonctionnalité | Effort | Phase |
+|---|---|---|
+| Synchronisation git automatique : settings.sync_repo, am sync, push à la fermeture du REPL | L | P2 |
+| Partage de catalogue d'équipe : include par URL | S | P2 |
+| am migrate — assistant de transfert machine A → B | M | P2 |
+| am serve --token — API HTTP + WebSocket pour piloter à distance | XL | P3 |
+
+### Axe 10 — 🧩 Confort & personnalisation
+
+🎯 Adapter am à sa façon de travailler.
+
+| Fonctionnalité | Effort | Phase |
+|---|---|---|
+| Favoris : am favorite / am unfavorite + ⭐ dans am list | S | P1 |
+| Notes : am note claude-code "utiliser pour …" | S | P1 |
+| Tags personnels : am tag claude-code python | S | P1 |
+| Raccourcis de commandes : settings.shortcuts (i → install, s → start) | S | P1 |
+| Profils d'environnement : am profile dev / prod (env + args + agent par profil) | M | P1 |
+| Thèmes couleurs du REPL | S | P2 |
+
+### Axe 11 — 🎛️ Modèles locaux
+
+🎯 Étendre le cockpit aux modèles : **ollama, llama.cpp, LM Studio**.
+
+| Fonctionnalité | Effort | Phase |
+|---|---|---|
+| am models — inventaire : nom, taille disque, quantisation, dernière utilisation | M | P2 |
+| Lien agent ↔ modèle : am run mon-agent --model llama3.1 | M | P2 |
+| doctor vérifie ollama / llama-server comme n'importe quel outil | S | P2 |
+| am models prune — purge des modèles inutilisés | S | P2 |
+
+### Axe 12 — 🛠️ Écosystème & expérience développeur
+
+🎯 Rendre am disponible partout et contribuable.
+
+| Fonctionnalité | Effort | Phase |
+|---|---|---|
+| Fixtures d'événements rejouables + tests de bout en bout du journal | S | P0 |
+| Packaging officiel : winget, scoop, deb/rpm, Homebrew + CI de release | M | P1 |
+| Complétions dynamiques (agents installés, groupes personnalisés) | S | P1 |
+| Man pages + documentation générée | S | P1 |
+| i18n : messages EN/FR | L | P2 |
+| Plugin scripts (hooks avancés, intégration CI) | M | P2 |
+
+---
+
+## 8. 🚀 Jalons versionnés
+
+| Jalon | Version | Contenu principal | Durée | Critère de sortie |
+|---|---|---|---|---|
+| **J0 — Fondations** | v0.3.0 | events.jsonl, sessions, am stats, am log, am history, am init, quick wins | ≈ 2 sem | 100 % des actions tracées · 100+ tests |
+| **J1 — Cockpit** | v0.4.0 | recherche fuzzy, Ctrl-R, projects, timeline, dashboard TUI, hooks, secret, favoris, packaging | ≈ 3 sem | retrouver n'importe quelle action passée en < 2 s |
+| **J2 — Automatisation** | v0.5.0 | watch, services, schedule, news/compare, catalogue distant, lab, models, sync | ≈ 4 sem | parc auto-supervisé (crash = redémarrage + alerte) |
+| **J3 — Plateforme** | v1.0 | am web, am serve, am ask, registry, télémétrie opt-in, sandbox | ≈ 6 sem | dashboard web complet + API distante |
+
+---
+
+## 9. 📈 Indicateurs de succès (KPI)
+
+| Indicateur | Cible |
+|---|---|
+| Part des actions tracées dans events.jsonl | 100 % dès la v0.3.0 |
+| Temps pour retrouver une commande ou session passée | < 2 s |
+| am list à chaud, journal actif | < 100 ms |
+| Dépendances runtime ajoutées | 0 |
+| Couverture de tests | ≥ 100 tests en v0.3, +25 par jalon |
+| Contrats --json cassés entre versions mineures | 0 |
+
+---
+
+## 10. ⚠️ Risques & garde-fous
+
+1. **ADN « zéro runtime »** : toute dépendance nouvelle est compilée dans le
+   binaire, jamais requise à l'exécution.
+2. **Performance** : le journal grossit — fenêtres temporelles, index dérivés,
+   rotation mensuelle, caches façon probe.rs.
+3. **Vie privée** : local par défaut ; télémétrie opt-in, agrégée, anonyme.
+4. **Contrats --json** : ajout de champs sans retrait (scripts utilisateurs).
+5. **Compatibilité** : migrations additives ; les exports 0.2.x restent
+   importables en 0.3+.
+6. **Complexité UX** : les fonctions avancées restent derrière
+   settings.experimental jusqu'à maturité.
+7. **Périmètre** : rester un orchestrateur — ne pas réimplémenter les
+   fonctionnalités propres aux agents (tokens, MCP, prompts), sauf valeur
+   transversale (stats, sessions, secrets, coûts).
+
+---
+
+## 11. 🏁 Par où commencer
+
+*Ordre de construction proposé pour la phase 0 — chaque étape est un PR
+indépendant et testé :*
+
+1. **PR 1** — src/events.rs : journal JSONL + rotation + tests.
+2. **PR 2** — instrumentation start/stop/run (process.rs, run_cmd.rs).
+3. **PR 3** — state.json v2 + migration additive.
+4. **PR 4** — sessions.json + am sessions + réconciliation.
+5. **PR 5** — am stats + am log (lecture du journal).
+6. **PR 6** — historique structuré + am history (migration de history.txt).
+7. **PR 7** — am init + détection de contexte (git, stack, cache).
+8. **En parallèle** — les quick wins de la section 3 (am logs, am list --sort,
+   am alias add, am config set, am version --json).
+
+---
+
+*Document généré à partir de l'analyse du code (v0.2.7, commit d886de3).
+Chaque item peut être chiffré et planifié indépendamment ; les phases 1 à 3
+seront détaillées dans des documents dédiés au moment de leur démarrage.*