agent-manager/ARCHITECTURE.md

# 🏗️ Document d'architecture — agent-manager (`am`)

> Ce document décrit la conception, le fonctionnement et les fonctionnalités de **agent-manager** (binaire `am`), un CLI Rust multiplateforme pour gérer des agents IA de coding locaux.
>
> 📦 Version : `0.4.3` · 🦀 Rust 2021 · ✅ Windows · ✅ Linux · ✅ macOS

---

## 🎯 Vue d'ensemble

`am` est un gestionnaire d'agents IA de coding qui permet de :

- 📋 Découvrir et lister plus de **72 agents** via un catalogue YAML embarqué
- 📦 Les installer avec **9 méthodes** différentes (npm, pip, uv, cargo, go, bun, curl, binaire, git)
- 🚀 Les démarrer, arrêter, redémarrer en avant-plan ou en arrière-plan
- 🔍 Observer leur état, leurs logs, leurs statistiques d'utilisation
- 🛠️ Gérer dépendances, alias, groupes, profils, secrets, favoris et annotations

Le tout sans toucher au système : chaque agent est installé dans un répertoire utilisateur isolé.

---

## 🧩 Architecture globale

```mermaid
flowchart TB
    subgraph UI["🖥️ Interfaces utilisateur"]
        CLI["Ligne de commande<br/>clap v4"]
        REPL["Shell interactif<br/>rustyline"]
        TUI["Dashboard TUI<br/>ratatui + crossterm"]
    end

    subgraph CORE["⚙️ Noyau applicatif"]
        APP["App<br/>contexte partagé"]
        CLI_DEF["cli.rs<br/>définition des commandes"]
        CMD["commands/<br/>dispatch"]
    end

    subgraph DATA["💾 Données persistantes"]
        CONFIG["Configuration YAML<br/>embarquée + utilisateur"]
        CATALOG["Catalog<br/>index agents/alias/groupes"]
        STATE["StateStore<br/>state.json"]
        EVENTS["Journal JSONL<br/>events-YYYYMM.jsonl"]
        CACHE["Probe cache<br/>probe-cache.json"]
    end

    subgraph EXEC["🔧 Exécution"]
        RUNNER["Runner trait<br/>système / mock"]
        INSTALLERS["installers/<br/>9 méthodes"]
        DEPS["deps.rs<br/>vérification dépendances"]
        PROCESS["process.rs<br/>PID / signaux"]
    end

    subgraph OBS["👁️ Observation"]
        PROBE["probe.rs<br/>détection agents externes"]
        DASH["dashboard.rs<br/>agrégation"]
        STATS["stats.rs<br/>statistiques"]
        SESSIONS["sessions.rs<br/>registre sessions"]
    end

    CLI --> APP
    REPL --> APP
    TUI --> APP
    APP --> CLI_DEF
    APP --> CONFIG
    APP --> CATALOG
    APP --> STATE
    APP --> EVENTS
    APP --> CACHE
    CMD --> RUNNER
    CMD --> INSTALLERS
    CMD --> DEPS
    CMD --> PROCESS
    CMD --> PROBE
    CMD --> DASH
    CMD --> STATS
    CMD --> SESSIONS
```

---

## 🚀 Flux d'exécution d'une commande

```mermaid
sequenceDiagram
    autonumber
    participant User
    participant main as main.rs
    participant lib as lib.rs
    participant help as help.rs
    participant cli as cli.rs
    participant app as app.rs
    participant cfg as config.rs
    participant state as state.rs
    participant cmd as commands/mod.rs
    participant impl as commands/xxx_cmd.rs

    User->>main: am install jcode
    main->>lib: main_entry()
    lib->>lib: spawn thread 8 Mo
    lib->>help: intercept(-h/--help) ?
    help-->>lib: None
    lib->>cli: Cli::parse()
    cli-->>lib: Cli { command: Install {...} }
    lib->>app: App::from_cli(cli)
    app->>cfg: load() config embarquée + user
    cfg-->>app: Config
    app->>state: StateStore::new()
    state-->>app: state.json chargé
    app-->>lib: App
    lib->>cmd: commands::execute(&app)
    cmd->>impl: install_cmd::run(...)
    impl->>impl: vérifier dépendances, installer
    impl->>state: persister
    impl->>app: emit(event install)
    impl-->>cmd: Ok(0)
    cmd-->>lib: 0
    lib-->>main: code sortie
```

---

## 📁 Structure du code source

```
src/
├── main.rs              🚪 Point d'entrée
├── lib.rs               🧭 main_entry(), doc du crate
├── cli.rs               📋 Définition clap de toutes les commandes
├── app.rs               🧰 Contexte App (config, state, paths, logger, theme)
├── config.rs            ⚙️ Schéma YAML, chargement, fusion, validation
├── catalog.rs           🔍 Index agents + recherche fuzzy + suggestions
├── state.rs             💾 Base JSON des installations et annotations
├── events.rs            📝 Journal d'événements JSONL
├── runner.rs            🏃 Trait d'exécution système / mock
├── process.rs           ⚙️ Lancement, arrêt, signaux des processus
├── deps.rs              ✅ Vérification et auto-installation des dépendances
├── toolchain.rs         🖥️ Détection OS / gestionnaire de paquets
├── download.rs          ⬇️ Téléchargement, checksums, extraction
├── probe.rs             🔎 Détection des agents externes sur le PATH
├── dashboard.rs         📊 Données agrégées du dashboard
├── ps.rs                🧮 Table des processus
├── context.rs           📂 Contexte du projet courant
├── repl.rs              💬 Shell interactif
├── shell.rs             🐚 Gestion des shells supportés
├── help.rs              ❓ Aide Nushell-style
├── output.rs            🖨️ Logger et rendu
├── tables.rs            📋 Rendu tabulaire
├── theme.rs             🎨 Thèmes de couleur
├── history.rs           ⏪ Historique des commandes
├── sessions.rs          📅 Registre des sessions
├── projects.rs          🗂️️ Agrégation par projet
├── hooks.rs             🪝 Hooks de cycle de vie
├── secrets.rs           🔒 Gestion des secrets (keyring OS)
├── version.rs           🏷️ Informations de version
├── commands/            📦 35 modules, un par commande
└── installers/          📦 9 installateurs spécialisés
```

---

## ⚙️ Configuration : catalogue YAML extensible

### Hiérarchie de chargement

```mermaid
flowchart LR
    EMB["📦 config.yaml<br/>embarqué dans le binaire"] --> MERGE["🔀 Fusion"]
    USER["👤 ~/.config/agent-manager/config.yaml"] --> MERGE
    LOCAL["📂 ./agent-manager.yaml"] --> MERGE
    FLAG["⚡ --config <file>"] --> MERGE
    MERGE --> EFFECTIVE["✅ Configuration effective"]
```

Priorité (la plus prioritaire en dernier) :

1. `config.yaml` embarqué (catalogue par défaut, ~72 agents)
2. `~/.config/agent-manager/config.yaml`
3. `./agent-manager.yaml` (configuration locale par projet)
4. `--config <fichier>`

### Schéma de configuration

```yaml
version: "1.0"

settings:
  install_dir: null            # ~/.local/share/agent-manager/agents
  log_dir: null                # ~/.local/state/agent-manager/logs
  default_shell: null          # shell utilisateur par défaut
  auto_install_deps: true      # proposer d'installer les dépendances manquantes
  confirm_before_run: true     # confirmer avant les scripts d'installation
  stop_timeout_secs: 5         # délai SIGTERM → SIGKILL
  self_update_repo: Projets/agent-manager
  self_update_base_url: https://git.dracodev.net/api/v1
  theme: null
  hooks:
    on_install: []
    on_start: []
    on_stop: []
    on_update: []

aliases:
  cc: claude-code
  gemini: gemini-cli

groups:
  dev: [claude-code, aider, codex]

include:
  - ./extra-agents.yaml

agents:
  - name: claude-code
    display_name: "Claude Code"
    description: "..."
    category: coding-agent
    website: https://github.com/anthropics/claude-code
    install:
      type: npm
      package: "@anthropic-ai/claude-code"
    dependencies:
      - { name: node, min_version: "18.0.0" }
    run: claude
    tags: [anthropic, assistant]

profiles:
  dev:
    agent: claude-code
    env: { API_ENV: dev }
    args: [--verbose]

projects:
  mon-projet:
    root: ~/projets/mon-projet
    default_agent: claude-code
    env: { KEY: value }
```

### Définition d'un agent (`AgentDef`)

| Champ | Description |
|-------|-------------|
| `name` | Identifiant unique (slug) |
| `display_name` | Nom lisible |
| `description` | Description longue |
| `category` | Catégorie (coding-agent, assistant, local-first...) |
| `website` | URL du projet |
| `install` | Spécification d'installation |
| `dependencies` | Outils requis (node, python, go...) avec version min |
| `run` | Commande de lancement |
| `args` | Arguments par défaut |
| `env` | Variables d'environnement par défaut |
| `tags` | Tags pour recherche/filtrage |
| `installable` | `false` pour les agents SaaS/Desktop |
| `platforms` | Restriction `linux`/`macos`/`windows` |

### Méthodes d'installation supportées

| Type | Fichier | Principe |
|------|---------|----------|
| `npm` | `installers/npm.rs` | `npm install -g --prefix <root>` |
| `bun` | `installers/npm.rs` | `bun install -g` |
| `pip` / `uv` | `installers/pipuv.rs` | virtualenv privé dans `install_dir` |
| `cargo` | `installers/cargo.rs` | `cargo install --root` |
| `go` | `installers/golang.rs` | `go install` avec `GOBIN` local |
| `curl` | `installers/script.rs` | Télécharge et exécute un script |
| `binary` | `installers/binary.rs` | Release GitHub/Gitea → extraction archive |
| `git` | `installers/git.rs` | Clone + build + `binary_path` |

---

## 💾 Gestion des états

### `state.json` — base d'installation locale

Format JSON version 3, atomique (écriture `.tmp` + `rename`).

```json
{
  "version": 3,
  "installed": {
    "jcode": {
      "name": "jcode",
      "version": "0.76.0",
      "method": "binary",
      "directory": ".../agents/jcode",
      "binaries": ["jcode"],
      "pid": null,
      "installed_at": "...",
      "updated_at": "..."
    }
  },
  "annotations": {
    "jcode": {
      "favorite": true,
      "note": "mon agent préféré",
      "tags": ["perso"]
    }
  }
}
```

### Journal d'événements JSONL

- Un fichier par mois : `events-YYYYMM.jsonl`
- Append-only, horodaté
- Types d'événements : `start`, `stop`, `run`, `install`, `update`, `uninstall`, `doctor`, `config`, `repl`, `shell`, `annotate`
- Les secrets ne sont jamais journalisés
- Source de vérité pour les statistiques, sessions, projets et timeline

### Cache de sondes

`probe-cache.json` évite de re-scanner le PATH à chaque commande pour détecter les agents externes et leurs versions.

---

## 🛡️ Gestion des dépendances

```mermaid
flowchart LR
    INSTALL["am install jcode"] --> CHECK["deps::check_dep"]
    CHECK --> MISSING{Manquant ?}
    MISSING -->|Oui| DETECT["toolchain::detect OS"]
    DETECT --> COMMANDS["toolchain::install_commands"]
    COMMANDS --> PROMPT["Proposer la commande"]
    PROMPT --> AUTO["Exécuter si --yes"]
    AUTO --> INSTALL2["installers::run_install"]
    MISSING -->|Non| INSTALL2
```

- `deps.rs` vérifie chaque dépendance via `<outil> --version`
- `toolchain.rs` détecte l'OS et le gestionnaire de paquets :
  - Windows : `scoop` → `winget`
  - Linux : `apt` / `dnf` / `pacman` / `apk`
  - macOS : `brew`
- Si `auto_install_deps: true`, `am` propose et peut exécuter la commande d'installation
- Les dépendances de l'agent (modules npm/pip) restent isolées dans le répertoire `install_dir`

---

## ⚡ Gestion des processus

```mermaid
flowchart TB
    START["am start <agent>"] --> MODE{Mode ?}
    MODE -->|Foreground| FG["Attache au terminal<br/>Ctrl-C pour quitter"]
    MODE -->|Background| BG["spawn_background()"]
    BG --> LOG["Redirection stdout/stderr<br/>vers log agent"]
    LOG --> PID["Enregistrement PID<br/>dans state.json"]
    PID --> EVENT["Émission événement start"]

    STOP["am stop <agent>"] --> SIGTERM["SIGTERM"]
    SIGTERM --> WAIT{"Processus terminé ?"}
    WAIT -->|Non| SIGKILL["SIGKILL après timeout"]
    WAIT -->|Oui| CLEAN["PID effacé"]
```

- Démarrage avant-plan (`-f`) ou arrière-plan (`-b`, `--background`)
- Variables d'environnement injectées via `--env KEY=VALUE`
- Secrets via `--env KEY=@secret` (résolu depuis le trousseau OS)
- Arrêt gracieux avec timeout configurable (défaut 5 s)
- Notifications desktop optionnelles (`--notify`)

---

## 📋 Commandes détaillées

### 🔍 Découvrir

| Commande | Description |
|----------|-------------|
| `am list` | Agents installés + détectés sur le PATH |
| `am list --all` | Tout le catalogue avec état |
| `am search <mot>` | Recherche fuzzy avec suggestions |
| `am info <agent>` | Fiche détaillée |
| `am status [agent]` | État, version, PID, logs |

### 📦 Cycle de vie

| Commande | Description |
|----------|-------------|
| `am install <agent>` | Installe un agent et ses dépendances |
| `am install <agent> --method pip` | Choisit la méthode |
| `am uninstall <agent> [--purge]` | Désinstalle et nettoie |
| `am update <agent>` / `--all` | Met à jour |
| `am start [agent]` | Lance en avant-plan |
| `am start <agent> -b` | Lance en arrière-plan |
| `am stop <agent>` | Arrêt gracieux |
| `am restart <agent>` | Redémarrage |
| `am run <agent> [args...]` | Exécution directe sans gestion de PID |

### 👁️ Observer

| Commande | Description |
|----------|-------------|
| `am logs <agent>` | Tail du log agent |
| `am log [agent]` | Journal des événements `am` |
| `am timeline` | Vue chronologique unifiée |
| `am sessions [agent]` | Registre des sessions |
| `am stats [agent] --period 7d` | Statistiques d'utilisation |
| `am top --period 30d` | Top 10 agents |
| `am report --last-week` | Rapport markdown |
| `am projects [nom]` | Agents par projet |
| `am dashboard` | Dashboard TUI temps réel |
| `am watch <agent> --restart` | Supervision et relance automatique |

### 🎯 Personnaliser

| Commande | Description |
|----------|-------------|
| `am favorite <agent>` | Marquer comme favori |
| `am note <agent> <texte>` | Ajouter une note |
| `am tag <agent> <tag>` | Taguer |
| `am tags [agent]` | Lister les tags |
| `am profile list/show <name>` | Profils d'environnement |
| `am alias add <nom> <cible>` | Créer un alias |
| `am secret set <nom> --agent <a> --value <v>` | Secret dans le trousseau |

### 🛠️ Système

| Commande | Description |
|----------|-------------|
| `am doctor [--fix]` | Diagnostic environnement |
| `am config show/path/edit/validate/set` | Gestion config |
| `am completion <shell>` | Script de complétion |
| `am man [commande]` | Page de manuel |
| `am open <agent>` | Ouvrir le répertoire d'installation |
| `am export/import` | Sauvegarde/restauration |
| `am self-update [--check]` | Mise à jour de `am` |
| `am self-uninstall` | Désinstallation complète |
| `am version` | Version et build |
| `am` (sans commande) | REPL interactif |

---

## 🌐 Options globales

Disponibles avant ou après la sous-commande.

| Option | Effet |
|--------|-------|
| `-c, --config <FILE>` | Fichier de configuration alternatif |
| `-v, --verbose` | Affiche chaque commande exécutée |
| `-q, --quiet` | Seules les erreurs sont affichées |
| `-y, --yes` | Oui à toutes les confirmations |
| `--dry-run` | Simulation sans modification |
| `--json` | Sortie JSON structurée |
| `--no-color` | Désactive les couleurs |
| `--theme <THEME>` | Thème de couleur |

---

## 🎨 Fonctionnalités avancées

### Alias

```yaml
aliases:
  cc: claude-code
  gemini: gemini-cli
```

`am start cc` démarre `claude-code`.

### Groupes

```yaml
groups:
  dev: [claude-code, aider, codex]
```

`am start group:dev` démarre tous les agents du groupe en arrière-plan.

### Profils d'environnement

```yaml
profiles:
  dev:
    agent: claude-code
    env: { API_ENV: dev }
    args: [--verbose]
```

`am start --profile dev` lance `claude-code` avec les variables et arguments du profil.

### Projets

```yaml
projects:
  mon-projet:
    root: ~/projets/mon-projet
    default_agent: claude-code
```

Dans le répertoire du projet, `am start` sans argument lance l'agent par défaut du projet.

### Secrets

Les secrets sont stockés dans le trousseau du système d'exploitation (via `keyring`), jamais en clair dans la config.

```bash
am secret set OPENAI_API_KEY --agent claude-code --value sk-...
am start claude-code --env OPENAI_API_KEY=@secret
```

### Hooks

Commandes exécutées automatiquement aux étapes clés du cycle de vie :

- `on_install`
- `on_start`
- `on_stop`
- `on_update`

Définissables globalement dans `settings.hooks` ou par projet.

### Shell interactif (REPL)

Lancé par `am` sans sous-commande :

- Complétion Tab personnalisée (commandes, agents, alias, groupes, flags, shells, thèmes)
- Historique des commandes
- Passerelle système : commandes inconnues exécutées dans le shell actif
- Commandes internes : `ls`, `dir`, `cd`, `ps`, `where`, `get`, `shell`, `theme`, `exit`, `/help`
- Bannière ASCII art

---

## 📊 Dashboard TUI

```mermaid
flowchart LR
    DASH["am dashboard"] --> OVER["Overview"]
    DASH --> ACT["Activité"]
    DASH --> STATS["Statistiques"]
    DASH --> SESS["Sessions"]
    DASH --> PROJ["Projets"]
```

- Navigation : `Tab` / `←` / `→` pour les onglets
- Défilement : `j` / `k` ou flèches
- Quitter : `q`
- Données agrégées depuis `state.json`, le journal d'événements, les sessions et les projets

---

## 🧪 Tests

### Organisation

- **Tests unitaires** : dans chaque module `src/*.rs` sous `#[cfg(test)]`
- **Tests d'intégration** : dans `tests/`

### Fichiers de tests notables

| Fichier | Couverture |
|---------|------------|
| `annotations_test.rs` | Favoris, notes, tags |
| `config_test.rs` | Chargement/validation/fusion |
| `dashboard_test.rs` | Dashboard |
| `doctor_test.rs` | `am doctor` |
| `dry_run_test.rs` | Mode `--dry-run` |
| `events_test.rs` | Journal d'événements |
| `history_test.rs` | Historique |
| `process_test.rs` | Processus |
| `profiles_test.rs` | Profils |
| `projects_test.rs` | Projets |
| `sessions_test.rs` | Sessions |
| `stats_test.rs` | Statistiques |

Lancer les tests :

```bash
cargo test
```

---

## 📦 Packaging et distribution

```
dist/                    Binaires précompilés
├── am-linux-x86_64
├── am-linux-aarch64
├── am-windows-x86_64.zip
├── am_0.4.3_amd64.deb
└── ...

packaging/              Scripts de packaging
├── deb/
├── rpm/
├── homebrew/
├── scoop/
└── winget/

completions/            Scripts de complétion
├── _am                 zsh
├── _am.ps1             PowerShell
├── am.bash             bash
├── am.elv              elvish
└── am.fish             fish

man/                    Pages de manuel générées
```

- `build.rs` enregistre le commit et la branche git pour `am version`
- `scripts/build-release.ps1` construit les releases multiplateformes
- `scripts/render-manifests.ps1` génère les manifests de packaging

---

## 🗂️️ Arborescence des données utilisateur

### Windows

```
%LOCALAPPDATA%\agent-manager\
├── agents\              installations
├── logs\                logs agents
└── state\               state.json, events-*.jsonl, probe-cache.json
```

### Linux

```
~/.local/share/agent-manager/   données
~/.local/state/agent-manager/   logs, state, events, cache
~/.config/agent-manager/        config.yaml
```

### macOS

```
~/Library/Application Support/agent-manager/   données
~/.local/state/agent-manager/                  logs, state, events, cache
~/.config/agent-manager/                       config.yaml
```

Variables d'environnement de débogage/test :

- `AGENT_MANAGER_DATA` : remplace le répertoire de données
- `AGENT_MANAGER_STATE` : remplace le répertoire d'état

---

## 🔐 Sécurité

- Mode `--dry-run` universel pour simuler sans modifier
- Checksums `sha256` pour les binaires téléchargés
- Confirmation avant exécution des scripts d'installation
- Secrets dans le trousseau OS, jamais dans les logs ni le journal
- Installation isolée : aucune modification système

---

## 🔁 Résumé du flux de données

```mermaid
flowchart LR
    CONFIG["📄 YAML config"] --> CATALOG["📚 Catalog"]
    CATALOG --> INSTALL["📦 Installateurs"]
    INSTALL --> STATE["💾 state.json"]
    STATE --> PROCESS["⚙️ Processus"]
    PROCESS --> EVENTS["📝 Journal JSONL"]
    EVENTS --> STATS["📊 Stats / Dashboard"]
    EVENTS --> SESSIONS["📅 Sessions"]
    EVENTS --> PROJECTS["🗂️️ Projets"]
```

---

## 📚 Références

- `src/lib.rs:4` : documentation d'architecture du crate
- `src/cli.rs:24` : options globales
- `src/cli.rs:61` : énumération des commandes
- `src/app.rs:16` : struct `App`
- `src/config.rs:25` : struct `Config`
- `src/config.rs:148` : struct `AgentDef`
- `src/config.rs:241` : enum `InstallType`
- `src/state.rs:12` : struct `StateFile`
- `src/events.rs:57` : struct `Event`
- `README.md` : documentation utilisateur complète

---

*Document généré pour agent-manager v0.4.3* 🚀