veille-ia-gen/README.md

# veille-ia

Observatoire personnel de veille sur les modèles IA génératifs (sorties, licences, classements), avec moteur de recommandation par profils de projets. Application privée, self-hosted, packagée pour YunoHost. Licence AGPL-3.0.

- **Spécification fonctionnelle** : [`plan_prd_veille_ia.md`](plan_prd_veille_ia.md)
- **Conventions frontend (prioritaires)** : [`SPECS_SVELTE.md`](SPECS_SVELTE.md)

## Structure du dépôt

| Chemin | Contenu |
|---|---|
| `app/` | Application SvelteKit (Svelte 5 runes, TypeScript strict, adapter-node) |
| `nodered-flows/` | Flows Node-RED exportés (phase 2 — à venir) |

Le package YunoHost vit dans son dépôt dédié : [`cyber-mawonaj/veille-ia-gen_ynh`](https://labola.o-k-i.net/cyber-mawonaj/veille-ia-gen_ynh) (clone local : `../veille-ia-gen_ynh`).

## Développement local (hors YunoHost)

Prérequis : Node 24 LTS, npm.

```bash
cd app
npm ci
npm run dev:local   # zéro config : utilisateur SSO simulé (dev), token d'alertes factice, données dans ./data
```

`npm run dev:local` injecte `DEV_USER=dev` (utilisateur SSO simulé — dev uniquement), `ALERTS_TOKEN=dev-token-local` (pour tester `POST /api/alerts`) et `DATA_DIR=./data`. L'app est sur http://localhost:5173, connectée en tant que `dev`.

Pour tester finement une variable précise, copie `.env.example` en `.env` et utilise `npm run dev`. Sans `DEV_USER`, l'accueil public minimal est affiché et toute autre route renvoie 401 — comme en production sans header SSO.

### Variables d'environnement

| Variable | Défaut | Rôle |
|---|---|---|
| `DATA_DIR` | `./data` (relatif à `app/`) | Dossier persistant : YAML + git interne. En prod : `/home/yunohost.app/veille-ia` |
| `OLLAMA_URL` | `http://127.0.0.1:11434` | Endpoint Ollama. Optionnel : dégradation gracieuse si injoignable |
| `ALERTS_TOKEN` | *(aucun)* | Token Bearer de `POST /api/alerts`. Généré à l'install YNH, jamais commité |
| `COMFYUI_URL` | `http://127.0.0.1:8188` | API ComfyUI pour les smoke tests. Dégradation gracieuse si injoignable |
| `SSO_HEADER` | `ynh-user` | Header HTTP injecté par SSOwat portant l'utilisateur authentifié |
| `DEV_USER` | *(aucun)* | Dev uniquement : simule un utilisateur SSO. Ignoré en production |
| `BASE_PATH` | *(aucun)* | Build uniquement : sous-chemin de montage (ex. `/veille`) pour `paths.base` |

### Qualité (à faire passer avant chaque commit)

```bash
npm run check   # svelte-check : 0 erreur, 0 warning
npm run lint    # prettier + eslint
npm run test    # vitest
npm run build   # build adapter-node
```

## Packaging YunoHost (dépôt `veille-ia-gen_ynh`)

Packaging v2 vérifié contre la documentation officielle (août 2026) et le schéma
`manifest.v2.schema.json`. Helpers 2.1 (`ynh_config_add_nginx`, `ynh_config_add_systemd`…).
Ressources : `ports`, `nodejs` (24), `system_user`, `install_dir` (`/var/www/veille-ia`),
`data_dir` (`/home/yunohost.app/veille-ia`). App privée : permission `all_users`,
identité transmise via le header `Ynh-User` (`proxy_params_with_auth`).

### Procédure de release (à suivre avant toute installation)

Le package consomme une **archive de tag** publiée sur la forge :

1. Pousser le dépôt sur `https://labola.o-k-i.net/cyber-mawonaj/veille-ia-gen` (procédure : `doc2sveltekit-transition/GITEA.md` — dépôt créé **sans** initialisation).
2. Taguer : `git tag v0.1.0 && git push gitea v0.1.0`.
3. Télécharger `https://labola.o-k-i.net/cyber-mawonaj/veille-ia-gen/archive/v0.1.0.tar.gz` et calculer son sha256.
4. Mettre à jour `manifest.toml` **dans le dépôt `veille-ia-gen_ynh`** : `version = "0.1.0~ynh1"`, `resources.sources.main.url` et `sha256` (le placeholder `TODO_…` actuel bloque volontairement toute installation), commit + push.
5. Vérifier avec `package_check` (sur une machine YunoHost de test) : viser niveau ≥ 7.

### Installation (sur le serveur)

```bash
yunohost app install https://labola.o-k-i.net/cyber-mawonaj/veille-ia-gen_ynh
# ou depuis un clone local : yunohost app install /chemin/vers/veille-ia-gen_ynh
```

L'install : déploie l'archive, `npm ci` + build (avec `BASE_PATH` = chemin d'install), génère `ALERTS_TOKEN`, écrit `/var/www/veille-ia/app/.env` (chmod 400), configure nginx + systemd (logs journald).

### Ollama

Optionnel. Si le paquet `ollama_ynh` est indisponible : Ollama sur la machine locale du porteur, exposé au serveur via wireguard/LAN — renseigner `OLLAMA_URL` à l'install (question du manifest) ou dans `/var/www/veille-ia/app/.env`. L'app démarre et fonctionne sans (dégradation gracieuse).

## État d'avancement

- [x] **Phase 0** — socle SvelteKit (SSO, thème OKI, CSP) + packaging YNH + dev local
- [x] **Phase 1** — registre + profils + moteur de recommandation + export markdown
  - Seeds au premier démarrage : `registre_modeles.yaml` (PRD §4.1), `profils_projets.yaml` (5 profils), templates markdown — commit git initial automatique dans le `DATA_DIR`
  - CRUD registre (`/registre`) et profils (`/profils`) : form actions, validation Zod, commit git à chaque écriture, champs tri-état (null = « à vérifier »)
  - Moteur de recommandation : page `/recommander` + API `POST /api/recommander` (JSON `{profil_id, filtres: {modalite?, vram_max?}}`, SSO requis) — filtrage dur puis scoring pondéré, justification et warnings par modèle
  - Exporteur markdown (`/exports`) : templates éditables, génération des guides depuis le registre, commit git par document
- [x] **Phase 2** — inbox alertes + flows Node-RED
  - `POST /api/alerts` : token Bearer (`ALERTS_TOKEN`, comparaison en temps constant), schéma d'alerte du PRD §4.4 validé par Zod, 503 si non configuré
  - Inbox `/alertes` : filtres par profil impacté et statut, actions « Marquer traité » et « Créer/MAJ fiche » (pré-remplissage du formulaire registre depuis l'alerte, sans inventer de champ)
  - `nodered-flows/` : 4 flows importables (rss-ingest, license-watch, classifier avec le prompt figé du PRD §6, notify) — nœuds core uniquement, configuration par variables d'env
- [x] **Phase 3** — templates ComfyUI + smoke tests
  - Templates paramétrés (`data/workflows/templates/`) : substitution de variables (`{{modele_checkpoint}}`, `{{resolution}}`, `{{vram_profile}}`…), **jamais de réécriture de topologie**
  - Génération de JSON concrets (`/workflows`) + **régénération automatique à chaque modification du registre**, commit git ; suppression si le modèle disparaît
  - Champ `comfyui_checkpoint` dans le registre ; génération refusée tant qu'il est null (anti-hallucination)
  - Smoke test : prompt canari sans modèle (EmptyImage→PreviewImage) posté sur `COMFYUI_URL/prompt`, statut remonté dans l'UI, dégradation gracieuse si injoignable
- [ ] **Phase 4** — durcissement (i18n gcf/en, niveau 8 package_check)