Files
CoHaiSe-CLOUD/docs/agents.md
T
Esiah cc397e96d8
PR — Ouverture automatique / create-pr (push) Failing after 1s
chore: initial import of CoHaiSe Cloud
Standalone files & media application: React/Vite frontend with the @cohaise/ui design system, Hono + MariaDB backend, nginx reverse proxy, Docker Compose stack, migrations 000-006, and project docs.

Adds Gitea Actions workflows for deployment, automatic pull requests, and Renovate dependency updates.
2026-10-14 15:24:06 +02:00

76 lines
3.3 KiB
Markdown

# 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** : `db_data` porte les
données, `media_data` les fichiers.
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
`frontend/shared` (`@cohaise/ui`) vit dans ce dépôt.
- `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`.