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 :

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.