# Agents — CoHaiSe Cloud Conventions pour reprendre ce dépôt seul. Démarrage rapide : `README.md`. Détails : `architecture.md`, `api.md`, `deployment.md`, `security.md`. ## Commandes | Action | Commande | | --- | --- | | Lever l'ensemble | `make up` | | Dev front | `make dev` (Vite 5174 → proxy 3101) | | Vérifier | `make check` (typecheck + build) | | Republier le front | `make front` | | Migrations | `make migrate` / `--check` via `docker compose run --rm migrate …` | | Sauvegarder | `make backup` | | Comptes | `make admin ARGS="--email … --first … --last …"` | | Journal / état | `make logs`, `make ps` | | Santé | `curl -I http://localhost:8083/healthz` | `make check` est le seul filet de sécurité automatique (ni linter, ni tests, ni CI). L'exécuter avant de déclarer un travail fini. ## Règles du dépôt 1. **Ne pas lire `.env`** : secrets de production. Écrire un `SESSION_SECRET` manquant est autorisé ; le diffuser, non. 2. **Ne pas committer ni pousser** sans demande explicite. 3. **Pas de `down -v`, pas de suppression de volume** : la base et les médias sont des bind mounts hôte (`$CLOUD_DB_DIR`, `$CLOUD_MEDIA_DIR`) — ne pas effacer ces dossiers. 4. **Ne jamais modifier une migration déjà appliquée** : nouveau fichier numéroté seulement. Le checksum bloquerait le démarrage. 5. **API admin** : les routes `/api/cloud/admin/*` existent (UI Administration). La CLI (`make admin`) reste pour l'amorçage et les cas hors ligne. 6. **Chemin disque** : toujours via `storage.ts` (`resolveInside`), jamais par concaténation depuis une entrée utilisateur. 7. **404 plutôt que 403** sur une ressource non accessible : ne pas introduire d'énumération. 8. **CSP stricte** : pas de script en ligne dans `index.html` (utiliser un fichier dans `public/`, comme `theme.js`). ## Conventions - TypeScript strict, project references racine. - Hono + Zod : toute route avec corps passe par un schéma Zod dédié. - Erreurs : `AppError` + codes (`errors.ts`) — jamais `throw` brut, jamais de détail de schéma dans une 500. - SQL : requêtes préparées uniquement, pas de `raw()` hors DDL. - Front : un seul client HTTP (`frontend/cloud/src/lib/api.ts`), `credentials: "same-origin"`. React Router 7 (`App.tsx`) + `AppShell`, contexte de session dans `lib/session.tsx`. - `.editorconfig` : 2 espaces, LF, UTF-8. ## Design system Le design system vit dans `frontend/cloud/src/ui`. - `tokens.css` est la source unique des couleurs et typographies ; ne pas coder de couleur en dur ailleurs. - Un composant propre à une page se développe dans `frontend/cloud`, pas dans le design system. - Palette : accent carmin `#b71c1c`, destructif rouge `#d32f2f`/`#ef4444`, avertissement jaune. Aucune orange. - **Aucun commit** : rien n'est encore historié, tout est untracked. ## Pièges - **`.env` ≠ `.env.example`** : comparer avant de conclure à un bug de port. - **README de paquet périmés** — utiliser ce dossier `docs/`. - **Build Docker et DNS** : les `build:` passent par `network: host` ; si `npm ci` échoue par `EAI_AGAIN`, le résolveur du démon est en cause. - **Limitation de débit active** (applicatif + nginx) : un test en rafale peut recevoir `419`/`503` côté API ou `503` nginx — ce n'est pas un bug. - Après `make up`, vérifier l'ordre : `migrate` doit être `exited (0)` avant que `api` ne devienne `healthy`.