Files
CoHaiSe-CLOUD/docs/agents.md
T
Esiah 93c6942cd5
PR — Ouverture automatique / create-pr (push) Successful in 3s
feat(ui): glass layout, icon actions and new icon set
2026-11-03 23:31:25 +01:00

3.5 KiB

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/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/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, 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: utilisent le réseau Docker par défaut. network: host est évité : Compose 5.6 / Buildx 0.38 refuse alors le build (additional privileges requested), sans transmettre --allow=network.host. Si npm ci échoue par EAI_AGAIN, corriger le DNS du démon Docker.
  • 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.