# 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 `` (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` → ``. - 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 -- ) 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.