system_update/CLAUDE.md

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Langue de travail

Répondre et documenter **en français**. C'est la langue du projet et de l'utilisateur.

## Nature du projet et état actuel

Objectif : construire une **webapp de mise à jour distante de machines Linux** (Debian, Ubuntu, Proxmox, Raspberry Pi OS) + Docker Compose, pilotée par SSH agentless, avec un copilote IA (« Hermes ») branché via un serveur MCP.

**Le projet est en phase de conception — l'application n'est pas encore initialisée.** Le dépôt ne contient pour l'instant que :

- `deep-research-report(7).md` — l'étude d'architecture de référence (stack, contrats JSON, flux, sécurité). **À lire avant toute décision d'architecture.**
- `ajout.md` — l'ajout du volet Hermes et le périmètre du serveur MCP.
- `design_system/` — le design system **Gruvbox seventies** à utiliser pour tout le frontend (voir section dédiée).
- `linux-update-dashboard/` et `nas-ops/` — **dépôts de référence en lecture seule** (voir ci-dessous).

Avant d'écrire du code applicatif, proposer/valider une structure avec l'utilisateur : ne pas figer l'architecture finale seul.

## Dépôts de référence (inspiration, PAS copie)

Ces deux dossiers sont des **sources d'analyse**, pas du code à recopier. Ne pas réutiliser de larges portions sans réécriture adaptée et vérification de licence.

- **`linux-update-dashboard/`** — licence **AGPL-3.0**. Excellent modèle d'**orchestration web agentless par SSH** : front React 19 + Vite + Tailwind 4, backend Hono, Drizzle + SQLite, SSH2, WebSocket de flux live (`/api/ws/systems/:id/output` avec messages `started`/`output`/`phase`/`done`/`error` et buffer rejouable), exécution détachée `nohup` survivant aux coupures SSH, credentials chiffrés au repos, host-key approval, ProxyJump. La contrainte AGPL impose de **reconstruire notre propre code**.
- **`nas-ops/`** — scripts Bash déterministes **JSON-friendly** (`nas-system-update`, `nas-system-upgrade`, `nas-docker-pull`, `nas-docker-up`). Modèle pour la **logique métier dans des scripts shell** qui détectent puis émettent un JSON compact (compare les image IDs avant/après pull, lit les labels compose). Licence non confirmée — traiter en référence.

Principe directeur issu de l'étude : **fusionner les deux** — orchestration web façon `linux-update-dashboard` + logique métier en templates shell versionnés façon `nas-ops`.

## Architecture cible (à construire)

Quatre couches, le backend **orchestre mais ne connaît pas la logique fine des mises à jour** :

1. **UI** — React + TypeScript + Vite. Pas de machine pré-déclarée ; ajout via bouton `+`.
2. **API** — Hono/TypeScript. Stocke machines, credentials (chiffrés), templates, jobs, rapports.
3. **Worker** — refresh et opérations longues en arrière-plan (file de jobs ; pg-boss sur Postgres recommandé en MVP).
4. **SSH/script runtime** — pousse les commandes, normalise les retours en **JSON canonique**.

La logique « comment mettre à jour APT / lister les stacks Docker » vit dans des **templates shell versionnés sur disque** (OS profile-aware), éditables depuis le front mais sauvegardés comme ressources de projet, avec overrides par machine. Ne pas stocker les commandes critiques uniquement en base.

Stack recommandée par l'étude : front shadcn/ui + Lucide, **Monaco** pour éditer les templates, **xterm.js** (couleurs ANSI, addon WebSocket) pour le terminal live à droite, layout `Resizable`. Backend Hono. Stockage **PostgreSQL + Drizzle** (plutôt que SQLite pour le projet final). Ces choix restent à confirmer avec l'utilisateur (cf. « Questions ouvertes » du rapport).

## Règles fonctionnelles (invariants)

- **`update`/`check` = tâche de fond** ; **`upgrade`/`full-upgrade`/`dist-upgrade`/`docker apply`/`reboot` = action manuelle validée** dans l'UI.
- Toujours distinguer **détection → planification → exécution**.
- Toujours produire un **JSON canonique par machine**. Deux schémas pivots : *update availability snapshot* et *execution result* (exemples complets dans `deep-research-report(7).md`).
- Après chaque exécution, **archiver un rapport `.md`** (et garder le log brut référencé, pas inliné).
- **Réduction déterministe avant tout appel LLM** : ne garder que les lignes utiles (APT : `Inst`/`Conf`/`Remv`/`Err`/`E:`/`W:`/`dpkg:`/`reboot-required` ; Docker : `Pulling`/`Digest`/`Status`/`Downloaded newer image`/`Recreating`/`Started`/`Error`). Le reste reste dans le log archivé.
- **Déduplication** des updates entre machines par empreinte fonctionnelle — système : `os_family + package + from + to + origin` ; Docker : `image + fromDigest + toDigest`.
- Docker : détecter via labels compose des conteneurs *en cours*, mais prévoir un **fallback par scan des répertoires Compose déclarés** (stacks non démarrées).

## Sécurité (non négociable)

- **Aucun secret ne transite vers un agent/LLM ni dans un prompt** : mots de passe SSH, sudo password, tokens, clés privées restent côté backend.
- **Aucun secret en clair** dans les logs, l'UI ou les retours MCP.
- Credentials **chiffrés au repos**. Vérification des host keys. Bastion/ProxyJump prévu. Utilisateur dédié de maintenance, sudo réduit au strict nécessaire.
- App pensée pour un **réseau de confiance** derrière reverse proxy/TLS/VPN, pas exposée directement à Internet.

## Hermes / serveur MCP

Hermes est un **copilote d'analyse**, la **webapp reste le chef d'orchestre**. Layout 3 zones : volet gauche = Hermes (chat, actions rapides, liens rapports), centre = dashboard machines, droite = terminal live.

- **Hermes n'exécute jamais de SSH directement.** Il passe uniquement par l'API interne / le serveur MCP, sur des actions explicitement autorisées, en consommant les JSON normalisés.
- Le **MCP est une façade** de l'API métier (pas de logique SSH dedans). Il ne reçoit jamais de secret ; les actions destructives exigent une validation côté webapp.
- Surface MCP volontairement **petite** (v1) : `list_machines`, `get_machine_snapshot`, `get_machine_execution`, `run_refresh`, `run_action`, `list_templates`, `preview_template`, `search_reports`. Contrats détaillés dans `deep-research-report(7).md` → `docs/MCP_CONTRACTS.md`.
- Le rôle d'Hermes : lire un snapshot, regrouper les doublons, recherche web ciblée sur les inconnus, proposer un plan court, rédiger un rapport Markdown. La skill `update-ops-planner` (gabarit dans le rapport) encapsule ce mode d'emploi.

## Design system — Gruvbox seventies (frontend)

**Tout le frontend doit suivre `design_system/consigne_design_system.md` — le lire en entier avant d'écrire du JSX.** Vibe rétro-industriel / console de monitoring. Règles dures :

- **Variables CSS uniquement**, jamais de hex en dur (`var(--accent)`, pas `#fe8019`). Toujours un `data-theme` (`dark`/`light`) sur un parent, et vérifier les deux thèmes.
- **Réutiliser les composants existants** de `design_system/components/ui-kit.jsx` (Button, IconButton, Toggle, StatusLed, RadialGauge, BatteryGauge, Popup, TreeNav, Sparkline, LineChart, Tooltip, Icon) avant d'en créer.
- **Icônes** via `<Icon name="…">` (noms mappés Font Awesome) — **jamais d'emoji ni de SVG inline custom**.
- **Pas de hover** sur boutons/tuiles (sauf jauges) — seulement la pression 3D `.interactive`. IconButton seul → `label` obligatoire (tooltip). Jamais `window.alert`/`confirm` → `<Popup>`.
- Polices strictes : **Inter** (UI), **JetBrains Mono** (données/IDs/IPs), **Share Tech Mono** (logs/terminal). Labels en uppercase `.label`.
- Tokens : `design_system/tokens/tokens.css` (web), `tokens.gnome.css` (GTK4/libadwaita), `tokens.json`.

## Commandes (dépôt de référence uniquement)

Le projet principal n'a pas encore de toolchain. Les commandes ci-dessous concernent **`linux-update-dashboard/`** (pnpm, Node 24, à lancer depuis ce sous-dossier) et servent de modèle pour notre futur setup :

```bash
pnpm install
pnpm dev            # serveur (tsx watch) + client (vite) en parallèle
pnpm build          # vite build && tsup
pnpm start          # node dist/server/index.js
pnpm test           # vitest run  (un seul test : pnpm test -- <pattern>)
pnpm check          # tsc --noEmit
```

## Fichiers de consigne à créer au démarrage

L'étude (`ajout.md`) liste les fichiers à mettre en place : `docs/CONSIGNE_PROJET.md`, `docs/ARCHITECTURE.md`, `docs/MCP_CONTRACTS.md`, `docs/HERMES_INTEGRATION.md`, `docs/SECURITY.md`, `docs/JSON_SCHEMAS.md`, `docs/TEMPLATES_UPDATE.md`, `hermes-skills/update-ops-planner/SKILL.md`, `mcp/README.md`, et les `templates/apt/*.sh.tpl` + `templates/docker/*.sh.tpl`. Les dépôts de référence sont à déplacer sous `references/` une fois le projet structuré.

## Posture attendue de l'agent

Pour toute proposition technique, distinguer **MVP recommandé / alternatives / risques**. Éviter les abstractions et générateurs opaques. Préférer des noms de dossiers explicites et une convention stable. En cas de doute sur l'architecture finale, **demander** plutôt que figer.