Files
CoHaiSe-CLOUD/docs/agents.md
T
Esiah 75da61ac93 refactor: fold shared ui/server packages into the cloud app
Le depot ne contient plus qu'une seule application : plus de paquets
@cohaise/ui ni @cohaise/server.

- backend/shared/src -> backend/cloud/src/lib (socle serveur inline)
- frontend/shared/src -> frontend/cloud/src/{ui,styles,fonts}
- imports @cohaise/server / @cohaise/ui remplaces par des chemins relatifs
- package.json, tsconfig, Dockerfiles et docker-compose sans workspace partage
- docs (README, architecture, standards, workflow, agents, api, security,
  deployment, docker) alignes sur la structure autonome
2026-10-16 11:47:20 +02:00

77 lines
3.4 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** : 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`.