112 lines
5.9 KiB
Markdown
112 lines
5.9 KiB
Markdown
# AGENTS.md — Instructions obligatoires du dépôt ObsiGate
|
|
|
|
> Ces instructions s'appliquent à **toute** intervention (humaine ou IA) sur ce dépôt.
|
|
> Documentation et réponses en **français**.
|
|
|
|
## Règle n°1 — Méthode de livraison unique
|
|
|
|
Avant toute tâche (fonctionnalité, bug, refactor), **lire et appliquer**
|
|
[`docs/DELIVERY_WORKFLOW.md`](./docs/DELIVERY_WORKFLOW.md) (Definition of Done).
|
|
Aucune tâche n'est terminée avant que sa checklist soit complète **et le CI vert**
|
|
(jobs `lint`, `test`, `security`, `build`, `e2e` de `.gitea/workflows/ci.yml`).
|
|
|
|
## Avant de commencer
|
|
|
|
1. Lire [`docs/ROADMAP.md`](./docs/ROADMAP.md) (travail à venir + index) et
|
|
[`docs/ISSUES_TODOLIST.md`](./docs/ISSUES_TODOLIST.md) (bugs).
|
|
2. Identifier ou créer l'**ID stable** (`#NN` pour une feature, `BUG-NNN` pour un bug —
|
|
jamais réutilisé) et passer son statut à « en cours » **avant** de coder.
|
|
|
|
## Architecture (ce qui n'est pas obvious)
|
|
|
|
- **Backend** : FastAPI/Python 3.11, point d'entrée `backend/main.py` (endpoints + rendu
|
|
markdown), index en mémoire (`indexer.py`, `search.py`), watcher (`watcher.py`),
|
|
auth dans `backend/auth/`. Pas de base de données : JSON dans `data/`.
|
|
- **Frontend** : vanilla JS **zéro framework, zéro build npm** (`frontend/app.js`,
|
|
`index.html`, `style.css`). Ne pas ajouter de dépendances npm ni d'étape de build.
|
|
- **Desktop** : Tauri (Rust) dans `desktop/` ; `tauri.conf.json` embarque `backend/**` et
|
|
`frontend/**` depuis `desktop/` — les scripts de build font le **staging** (copie) avant
|
|
`cargo tauri build`, sinon le build échoue.
|
|
- **i18n** : tout texte d'interface doit exister en FR **et** EN
|
|
(`frontend/locales/fr.json` + `en.json`).
|
|
|
|
## Vérifications locales (pwsh, à faire passer avant tout commit/push)
|
|
|
|
```powershell
|
|
# Backend (venv à la racine)
|
|
.\.venv\Scripts\python.exe -m pytest tests/
|
|
.\.venv\Scripts\python.exe -m ruff check backend/
|
|
.\.venv\Scripts\python.exe -m mypy backend/ --ignore-missing-imports
|
|
|
|
# Frontend : scripts Node à exécuter directement (pas de runner)
|
|
node tests/frontend/validate-imports.mjs
|
|
node tests/frontend/unit.test.mjs
|
|
# Tests JSDOM : node_modules dans tests/frontend/ (npm install là-bas si absent), ex :
|
|
node tests/frontend/pane-manager.test.mjs
|
|
|
|
# E2E (si UI touchée, ~10 min) : reproduit le job CI e2e (port 2029, auth désactivée)
|
|
npm run test:e2e # prérequis : uv, Node >= 20, npx playwright install chromium
|
|
bash scripts/run-e2e-local.sh -g "nom du test" # filtre / --headed
|
|
|
|
# Windows sans bash exploitable (WSL HS, git-bash bloqué par App Control) :
|
|
npm run test:e2e:ps # équivalent PowerShell, mêmes conditions que le CI
|
|
pwsh -File scripts/run-e2e-local.ps1 -PlaywrightArgs @('-g','nom du test')
|
|
```
|
|
|
|
- Un seul test backend : `.\.venv\Scripts\python.exe -m pytest tests/test_search.py -q`.
|
|
- **Sélection E2E** : vérifier chaque sélecteur dans le DOM réel avant de l'utiliser dans un
|
|
test ; tout test nouveau/modifié doit passer en local avant push ; pas de contournement
|
|
qui masque la flakiness (`waitForTimeout` arbitraires, fallbacks silencieux).
|
|
- La suite E2E doit finir à **100 %** sans s'appuyer sur les retries. Jamais de `git push`
|
|
avant que les 5 étapes locales soient vertes.
|
|
|
|
## Version & hooks (pièges)
|
|
|
|
- `VERSION` (racine) = **source unique de vérité** (SemVer), incrémenté **automatiquement à
|
|
chaque commit** par le hook `.githooks/prepare-commit-msg` — `feat` → mineur,
|
|
`!:` / `BREAKING CHANGE` → majeur, sinon correctif. Le même commit resynchronise
|
|
`package.json`, le desktop Tauri, `README.md`/`README.fr.md`, `docs/ROADMAP.md` et publie
|
|
la section `[Unreleased]` du `CHANGELOG.md` en `[X.Y.Z] — date` ; tag `vX.Y.Z` créé au
|
|
commit, publié au push (`push.followTags`).
|
|
- Hooks **obligatoires**, à installer une fois par clone : `scripts/install-hooks.sh`
|
|
(sinon la version ne suit plus et le CI échoue via le garde-fou `tests/test_version.py`).
|
|
- Le rattachement des fichiers de bump se fait par un `--amend` immédiat : **le SHA affiché
|
|
par `git commit` change** — ne pas s'y fier.
|
|
- Commit sans incrément (exceptionnel) : `SKIP_VERSION_BUMP=1 git commit …`.
|
|
- Ne jamais réécrire une version déjà publiée dans le CHANGELOG ; jamais de détail dupliqué
|
|
entre Roadmap et CHANGELOG.
|
|
|
|
## À la fin de chaque tâche (obligatoire)
|
|
|
|
- Tests unitaires ajoutés/mis à jour (correctif sans test de non-régression = pas terminé).
|
|
- Toutes les vérifications locales ci-dessus vertes (`E2E` si UI).
|
|
- Documentation mise à jour : `CHANGELOG.md` (`[Unreleased]`), `docs/ROADMAP.md` (statut +
|
|
index), fiche `docs/features/` **ou** `docs/archive/`, `docs/ISSUES_TODOLIST.md` (si bug),
|
|
guide utilisateur i18n FR/EN + README si impact utilisateur, docstrings +
|
|
`response_model` si API.
|
|
- **Commit** conventionnel référençant l'ID (`feat: … #12`), puis **push** et **CI vert**.
|
|
|
|
## Cartographie documentaire
|
|
|
|
| Sujet | Fichier |
|
|
|---|---|
|
|
| Méthode de livraison / DoD | `docs/DELIVERY_WORKFLOW.md` |
|
|
| Version livrée (source unique) | `VERSION` + `scripts/bump_version.py` |
|
|
| Travail à venir + index | `docs/ROADMAP.md` |
|
|
| Historique des versions | `CHANGELOG.md` |
|
|
| Conception par feature | `docs/features/<slug>.md` |
|
|
| Guides d'utilisation | `docs/GUIDES/` |
|
|
| Archive du complété | `docs/archive/COMPLETED_v1-v2.md` |
|
|
| Bugs / TODO | `docs/ISSUES_TODOLIST.md` |
|
|
| Build & releases | `docs/DEVELOPMENT_AND_RELEASES.md` |
|
|
| Standards de code | `docs/CONTRIBUTING.md` |
|
|
|
|
## Conventions
|
|
|
|
- Commits : `type: description` — `feat`, `fix`, `perf`, `refactor`, `docs`, `style`, `chore`, `test`.
|
|
- Sécurité : tout chemin fichier fourni par l'utilisateur passe par `_resolve_safe_path()`.
|
|
- **Ne jamais** committer de secrets, clés ou tokens (`.env` jamais committé ; secrets dans
|
|
`data/api_keys.json` ou variables `OBSIGATE_*`).
|
|
- Respecter le style du code existant (ruff/mypy 0 erreur ; CSS variables, pas de couleurs
|
|
hardcodées ; `safeCreateIcons()` plutôt que `lucide.createIcons()` direct).
|