@nodefony/devkit 10.0.0-beta.2 → 10.0.0-beta.4

package/skills/nodefony-dev/SKILL.md

@@ -14,7 +14,7 @@ description: >
   est-il fini", "je ne trouve rien sur ce sujet", "ce n'est pas documenté", "je touche au
   frontend", "mon composant charge des données", "mon écran n'affiche rien".
 metadata:
-  version: 1.2.0
+  version: 1.3.0
 ---
 
 # nodefony-dev — développer dans cette application sans rien inventer
@@ -45,15 +45,19 @@ de son geste, et ceux-là ne se devinent pas — ils se paient.
 | -------------------------------------------------------------------- | ------------------------------- |
 | Une ressource : table, validation, service, REST et WebSocket        | `nodefony-add-crud`             |
 | Une logique métier réutilisable, hors de tout controller             | `nodefony-add-service`          |
-| Un flux temps réel, un canal, un abonnement client                   | `nodefony-add-realtime-channel` |
-| Réserver une route, un rôle, une zone, ouvrir à un partenaire        | `nodefony-protect-route`        |
+| Un flux temps réel (WebSocket ou SSE), un canal, un abonnement       | `nodefony-add-realtime-channel` |
+| Se connecter : /login, second facteur, retour après connexion, jeton | `nodefony-authentication`       |
+| Réserver une route ou une page à des rôles, ouvrir à un partenaire   | `nodefony-protect-route`        |
 | Changer une entité déjà en base, ou déployer un schéma changé        | `nodefony-migrate-schema`       |
 | Conclure quoi que ce soit d'un ÉCRAN — affichage, contraste, console | `nodefony-browser`              |
+| Quelque chose qui marchait ne marche plus : démarrage, 404, journal  | `nodefony-troubleshoot`         |
+| Relire la sécurité de ton diff AVANT de commiter                     | `nodefony-security-review`      |
+| Monter Nodefony de version, ou une montée qui a laissé des rouges    | `nodefony-upgrade`              |
 
 Aucune ligne ne correspond ? Alors seulement, continue ici. Et si ta tâche est EXACTEMENT celle
 d'un spécialiste, va droit à lui : il n'y a pas à passer par cette page d'abord.
 
-`ls .agents/skills/` liste ceux que TON projet a reçus ; `npx nodefony ai:sync` les remet à jour
+`ls .agents/skills/` liste ceux que TON projet a reçus ; `npx nodefony upgrade` les remet à jour
 après une montée de version. Ce sont des **pointeurs** : le contenu vit dans `node_modules` et
 suit la version installée — les éditer ne servirait à rien.
 
@@ -124,6 +128,11 @@ Elle répond **toujours** — application pas encore construite, terminal sans a
 d'environnement : elle ne lit que des fichiers. Elle le DIT alors (« modules installés », pas
 « chargés ») et renvoie à `inspect modules` pour ce qui est vraiment monté.
 
+**`rg` ou outil MCP ?** Question étroite, format connu (un motif, un fichier) → `rg`, bien moins
+cher. Question ouverte sur l'application qui TOURNE (démarrage sain ? quelle route casse ?) →
+`nodefony_check` (= `nodefony doctor`), `nodefony_observe` : un appel au lieu de plusieurs `rg`,
+et des faits qu'aucun fichier ne porte.
+
 ```bash
 npx nodefony inspect routes --json     # routes réelles (chemin MONTÉ, méthodes, controller)
 npx nodefony inspect services --json   # services enregistrés, et le module qui les porte
@@ -152,7 +161,8 @@ npx nodefony symbols --module @nodefony/http  # toute la surface exportée d'un
 ```
 
 Le graphe symbolique de tout le framework est livré avec le paquet `nodefony` : la réponse ne
-dépend ni d'un serveur, ni d'un build, ni de ta connexion. Va y chercher un symbole AVANT d'ouvrir
+dépend ni d'un serveur, ni d'un build, ni de ta connexion. Celui de TON code (`.ai/symbols.json`),
+`npm run dev` le tient à jour — ou `npx nodefony symbols --generate` ; les deux sont lus ensemble. Va y chercher un symbole AVANT d'ouvrir
 un `.d.ts` — et avant, surtout, d'inventer une signature.
 
 **Si la commande te résiste, répare l'APPEL — ne te rabats pas sur les sources.** C'est le réflexe
@@ -165,31 +175,42 @@ tube, puis remets ton filtre.
 (`npx nodefony ai:mcp` écrit `.mcp.json`) — mêmes réponses, et tes propres modules peuvent publier
 les leurs. La porte est une ROUTE : elle n'existe que serveur démarré, et un client qui la trouve
 éteinte la marque en échec pour toute sa session — démarre l'application D'ABORD, ta session
-ENSUITE. Tout le reste (déclarer un outil métier, le réserver à des scopes, l'autorisation OAuth) :
+ENSUITE. Aucun serveur ne peut tourner (CI, agent dans un runner) ? Ton client lance lui-même
+`npx nodefony ai:stdio` et lui parle sur l'entrée et la sortie standard : mêmes outils, mais le
+code du démarrage, sans rechargement à chaud ni trafic réel à mesurer. Tout le reste (déclarer un outil métier, le réserver à des scopes, l'autorisation OAuth) :
 `node_modules/@nodefony/devkit/docs/index.md`.
 
+**Ta tâche est d'OFFRIR les outils de l'application à un agent** (« expose ceci par MCP ») ? Ce
+n'est pas la porte ci-dessus, qui sert l'outillage en développement : c'est une porte de
+l'APPLICATION, et elle se génère — n'écris pas le protocole à la main :
+
+```bash
+npx nodefony create controller mcp --kind mcp                  # porte locale : la machine seulement
+npx nodefony create controller mcp --kind mcp --expose oauth   # production : jeton exigé (401 sans)
+npx nodefony create controller mcp --kind mcp --expose mixte   # outils publics sans jeton, les autres réservés à un scope
+```
+
+Elle naît avec deux outils d'exemple (`nodefony/mcp/mcp-tools.ts`), sa définition
+(`defineMcpGate`, `nodefony/mcp/mcp-gate.ts`) et son test. Ajoute tes outils à la LISTE de la
+porte : elle publie ce qu'elle choisit, rien d'autre. Mode d'emploi :
+`node_modules/@nodefony/ai/docs/mcp.md` § « Monter une porte ».
+
 ### L'environnement : ne devine JAMAIS, demande
 
 ```bash
-npx nodefony env          # cascade des .env, valeur EFFECTIVE de chaque variable, sa PROVENANCE
+npx nodefony env          # valeur EFFECTIVE de chaque variable, sa PROVENANCE
 ```
 
 **Encadre toute modification de configuration par cette commande** : une fois AVANT, pour savoir ce
 qui s'applique et d'où ça vient ; une fois APRÈS, pour prouver que ta valeur est celle qui gagne.
-Lire les `.env` toi-même donne des contenus ; la précédence est un mécanisme — tu ne peux que la
-supposer, et une supposition fausse ne se voit qu'en production. La commande ne boote rien, donc
+Lire `.env` toi-même donne un contenu ; ce que l'application voit dépend aussi du shell et de
+`env.ts` — tu ne peux que le supposer, et une supposition fausse ne se voit qu'en production. La commande ne boote rien, donc
 elle répond aussi quand l'application ne démarre plus.
 
-**Précédence, du plus FORT au plus faible** — le premier qui pose une valeur gagne, les suivants
-sont ignorés en silence :
-
-```
-process.env  >  .env.<déploiement>.local  >  .env.<mode>.local  >  .env.local
-             >  .env.<déploiement>        >  .env.<mode>        >  .env
-```
-
-`<mode>` = `NODE_ENV` · `<déploiement>` = `APP_ENV` (plus spécifique, donc plus fort). Les `*.local`
-ne sont jamais committés : les secrets y vont, et nulle part ailleurs.
+**Deux fichiers** : `.env` = valeurs du POSTE (secrets de dev compris), **jamais commité** ;
+`.env.example` = notice commitée, **jamais chargée**. `process.env` > `.env`, rien d'autre. La
+production n'a **aucun** fichier (orchestrateur ; réglages non secrets dans `nodefony.config.ts`).
+Un module n'a pas de `.env`. N'écris JAMAIS `.env.local` ni `.env.<mode>` : refusés au démarrage (78).
 
 | Forme                                 | Ce que c'est                                         | Où c'est déclaré                                       |
 | ------------------------------------- | ---------------------------------------------------- | ------------------------------------------------------ |
@@ -261,6 +282,13 @@ une table à part — et ce nom est ce que `stop` accepte. Donc « aucune instan
 REFUSÉE, avec un code de sortie non nul et rien d'arrêté — **lis ce code**, un refus ressemble
 sinon à un succès.
 
+**Le plein écran n'est pas pour toi — et il est le DÉFAUT sous macOS et Linux.** Il fige la barre
+d'état en bas, capte le clavier et la souris (molette, PgUp/PgDn, Ctrl+C devient une touche) :
+c'est un écran pour un humain. Il s'active dès que le terminal répond à une sonde, et un
+pseudo-terminal (tmux, un outil qui t'en fournit un) y répond. Nodefony ne devine jamais qu'un
+agent est aux commandes : si tu lances `development` toi-même, ajoute **toujours** `--no-ui`
+(ou pose `NF_DEV_UI=0`), ou `--output plain` pour une sortie sans séquences d'écran.
+
 **Pour faire tourner une suite contre un serveur, prends `--no-watch`.** Le mode développement
 relance le serveur dès qu'un fichier bouge : pendant un run, le redémarrage coupe les connexions
 sous les tests, et le rouge qui en sort accuse le code alors que le fautif est le décor.
@@ -283,8 +311,9 @@ routes auth` ne rend que les routes dont le chemin, le nom, le contrôleur, l'ac
 4. **Édite le moins possible**, et regroupe : toutes les modifications serveur d'une même
    fonctionnalité, PUIS un seul cycle de reconstruction. Le frontend passe en HMR, zéro
    redémarrage.
-5. **Prouve.** `npm run verify` — une seule commande : types, style, tests, câblage, dans cet
-   ordre. Elle s'arrête au premier rouge, et **ce rouge est ta tâche suivante**.
+5. **Prouve.** `npm run verify` — une seule commande : types, style, mise en forme,
+   `.env.example`, tests, build, câblage, dans cet ordre. Elle s'arrête au premier rouge, et
+   **ce rouge est ta tâche suivante**.
 
 **Le point d'arrêt qu'on rate** : `npm test` seul ne prouve pas que ça compile — vitest
 n'inspecte aucun type. Une application peut être verte et ne pas compiler.
@@ -304,50 +333,19 @@ ici — ils changent tous les trimestres ; raisonne en poids.
 
 ## 7. Les pièges du serveur
 
-Chacun a déjà coûté au moins une heure à quelqu'un. Les quatre premiers sont les plus fréquents.
-
-- **Ta route répond 404 alors qu'elle existe dans les sources.** Le runtime charge `dist/`, pas
-  le source : `npm run build`. C'est la cause n°1.
-- **Une classe que rien ne déclare compile, passe ses tests, et casse au démarrage suivant** —
-  entité hors `@entities([…])`, controller hors `@controllers([…])`. Table jamais créée, route
-  en 404. C'est le mode d'échec de la COPIE : on recopie le voisin au lieu d'appeler le
-  générateur, qui, lui, déclare. `npx nodefony doctor` la NOMME.
-- **Une clé de configuration mal orthographiée est retirée en silence.** `satisfies` sur le
-  fragment n'est pas décoratif : sans lui, la faute compile, puis la validation écarte la clé et
-  le module démarre sur son défaut. Personne ne le voit.
+Ceux qu'on pose en ÉCRIVANT. Ceux qu'on rencontre quand quelque chose qui marchait ne marche plus
+— démarrage qui échoue, route en 404, refus inattendu, journal en erreur, tests rouges d'un coup —
+ont leur skill, qui part du symptôme : **`nodefony-troubleshoot`**.
+
+- **Une clé de configuration mal orthographiée ARRÊTE le démarrage** (code 78), en la nommant.
+  `satisfies` sur un fragment extrait n'est pas décoratif pour autant : il te la signale à la
+  compilation, au lieu du prochain démarrage.
 - **La config d'un module est FIGÉE après le démarrage** : l'écrire lève `TypeError`. Une variante
   par requête = `overlayConfig()` (clés de la liste blanche du module), lue par `useConfig()`.
 - **Tu lis une liste sans la BORNER.** Un `find` sans limite matérialise la table entière —
   indolore sur les quelques lignes du poste de développement, fatal sur les dizaines de milliers
   de la production. Le service d'une entité hérite `findPage({ limit: 25 })`.
 
-- **Des dizaines de tests d'intégration rouges d'un coup** (`ECONNREFUSED`) : ils FRAPPENT un
-  serveur, ils ne le lancent pas — il est éteint. `npx nodefony status` d'abord ; en e2e, laisse
-  la commande gérer le cycle.
-- **Ta route NEUVE répond 404 et le `dist/` est à jour** : elle n'est pas montée où tu crois. Le
-  chemin réel est le PRÉFIXE de son controller suivi du `path` de la route — une action
-  `path: "/widget"` dans un controller `@controller("/api")` répond sur `/api/widget`.
-  `npx nodefony inspect routes --json` donne le chemin MONTÉ.
-- **TOUT répond 404, même les routes du gabarit** : un AUTRE serveur tient les ports — ou LE TIEN
-  a glissé, le port voulu étant pris. `npx nodefony status` montre les ports RÉELS, pas ceux que
-  tu as configurés, et NOMME le projet voisin.
-- 🔴 **`nodefony <commande>` échoue là où `npm run dev` réussit, sur la MÊME application** : DEUX
-  paquets `nodefony` tournent dans le processus — un binaire lié ailleurs (installation globale,
-  `npm link`) exécute un noyau pendant que l'application importe le sien. Chaque copie a ses
-  propres classes, son contexte de requête et ses registres d'injection : un module construit à la
-  frontière perd son container SANS la moindre erreur — il figure dans la liste des modules et ne
-  fait rien. ⚠️ Les deux copies peuvent être la MÊME version ; deux fichiers distincts suffisent,
-  il n'y a aucune incohérence à repérer. `npm ls nodefony` liste les copies (« deduped » partout =
-  une seule) ; `NF_CLI_DEBUG=1 nodefony --version` dit quel CLI s'exécute.
-- **`localhost` et `127.0.0.1` te jouent des tours** : ce sont deux ORIGINES distinctes — cookies,
-  cache et passkeys ne les partagent pas. Une seule origine en développement, partout, URL ouverte
-  comme callbacks.
-
-- **Les routes authentifiées plafonnent quand le reste tient la charge** : le stockage de session
-  par défaut est SYNCHRONE — chaque reprise bloque la boucle d'événements. Compare une route
-  anonyme et une route authentifiée AVANT d'accuser TLS ou le pare-feu ; passe le stockage sur
-  redis pour la charge.
-
 ### Ce qui tue le processus, pas la requête
 
 - 🔴 **Une promesse lancée sans `await` porte TOUJOURS un `.catch()`.** Audit, courriel,
@@ -361,24 +359,6 @@ Chacun a déjà coûté au moins une heure à quelqu'un. Les quatre premiers son
 - **Un `PATCH` au corps vide se refuse en `400`.** Le laisser passer produit un `updateOne({})`,
   qui finit en `500 « No values to set »` — une erreur serveur pour une faute de client.
 
-### Quand ça ne va pas, et que le message ne suffit pas
-
-- **Un test vert seul et rouge en suite accuse une RESSOURCE PARTAGÉE**, pas ton code : base ou
-  index réutilisé, port, store jamais purgé, assertion `count === N` qui suppose une table
-  vierge. Lance deux fichiers ENSEMBLE pour isoler la paire, puis cloisonne. **Ne sérialise
-  jamais la suite** pour faire passer le rouge : tu masques la cause et tu paies la lenteur à
-  chaque exécution.
-- **Une suite lancée contre un serveur en `production` reçoit `404` partout** : les modules
-  `policy:"dev"` n'y sont pas. `NF_WITH_DEV_MODULES=1` déroge pour 30 minutes
-  (`NF_WITH_DEV_MODULES_TTL_MIN`, 4 h au plus), et le `CRITIC « arrêt automatique … dérogation »`
-  du journal est cette garde qui se referme — pas une panne.
-- **Ton application a démarré AMPUTÉE et tout a l'air sain** — base injoignable, module écarté
-  par sa politique. Seul `npx nodefony doctor` le dit, en relisant `var/last-boot.json`.
-  ⚠️ Ce bilan a un ÂGE : il décrit le **dernier démarrage**, et une commande console (`inspect`,
-  une commande de module) ne l'écrase pas. C'est voulu — lis la date avant d'en conclure.
-- **L'application ne démarre plus et le superviseur avale la sortie** :
-  `NF_DEV_CHILD=1 npx nodefony development` lance l'enfant seul et montre le crash brut.
-
 ## 8. Données et fichiers — les façades qu'on ne recompose pas
 
 - **Un cache ne remplace pas une base : ils se COMPLÈTENT.** Chaque adaptateur déclare les
@@ -386,6 +366,14 @@ Chacun a déjà coûté au moins une heure à quelqu'un. Les quatre premiers son
   huit, `redis` quatre (`session`, `tokens`, `passkeys`, `idempotency`) : un cache ne garde ni
   comptes ni journal d'audit. Ne promets jamais une parité qui n'existe pas — lis ce champ, et
   `npx nodefony inspect stores` dit où atterrit chaque donnée.
+- **L'entrée d'une route se DÉCLARE — ne la valide pas à la main.** L'option `schema` d'un
+  décorateur de route (`@Post("/posts", { schema: { params, query, body, headers } })`, un schéma Zod
+  par partie) fait valider l'entrée AVANT l'action — **422** qui nomme chaque champ et sa partie, sur
+  HTTP comme par la socket (`api.request`) — et l'action la reçoit typée en UN argument,
+  `input: RouteInput<…>`. Une action à schéma ne prend **aucun** décorateur de paramètre (`@Body`,
+  `@Query`…) : le mélange est refusé au démarrage, qui nomme la route. L'identité se lit par
+  `this.user`. Un corps binaire arrive en octets (`Uint8Array`), un `text/*` en chaîne : un même
+  `z.instanceof(Uint8Array)` vaut pour les deux portes. Doc : `node_modules/@nodefony/framework/docs/decorateurs.md`.
 - **Les violations de contrainte sont DÉJÀ traduites en HTTP — ne les rattrape pas.** Un doublon
   sur une colonne unique ressort en **409**, une donnée qui viole le schéma Zod en **422**, chacun
   avec son corps JSON : le rendu d'erreur lit le code du pilote (`23505`, `ER_DUP_ENTRY`,
@@ -454,11 +442,16 @@ Ne concerne qu'une application qui a un frontend. Sauf mention, **vaut pour les
   **couleur seule**, `rel="noopener noreferrer"` sur les liens externes.
 
 - **Une route d'API répond du HTML** : un repli SPA générique avale les routes voisines — le
-  premier motif qui correspond gagne. Repli en préfixe LITTÉRAL ; `npx nodefony inspect routes
---json` montre l'ordre réel.
+  premier motif qui correspond gagne. Déclare la route de la page monopage avec
+  `fallback: true` : elle ne sert alors que ce qu'aucune autre route ne sert, quel que soit
+  l'ordre. `npx nodefony inspect routes --json` montre l'ordre réel.
 - **Des utilisateurs « déconnectés au hasard »** : le traitement global « 401 = session expirée »
-  frappe aussi les sondes d'authentification, où 401 est NORMAL — et détruit une session valide.
-  Exempte les sondes du traitement global.
+  frappe aussi la connexion refusée (un mauvais mot de passe rend 401) — et détruit une session
+  valide. Exempte les routes d'authentification du traitement global. `me` ne renvoie jamais
+  401 : il répond toujours 200, `{ user: null }` sans session.
+- **La connexion ne s'écrit pas en `fetch`** : `/login` est servie ; la liaison du front
+  (`useNodefonyLogin`…) porte `me()` et `logout()` — suis l'adresse que rend `logout()`, sinon
+  la session Keycloak reste ouverte. Détail : skill `nodefony-authentication`.
 - **Ta page répond 200 et son script ne s'exécute pas** : la politique de contenu exige un `nonce`
   sur les scripts, et le navigateur refuse un `<script>` en ligne qui n'en porte pas (« Refused to
   execute inline script »). Un `curl` ne le voit JAMAIS, il ne lit que le corps. Signe le script
@@ -477,10 +470,13 @@ Ne concerne qu'une application qui a un frontend. Sauf mention, **vaut pour les
 ## 10. Avant de dire « fait »
 
 ```bash
-npm run verify        # types + style + tests + câblage
+npm run verify        # types, style, mise en forme, .env.example, tests, build, câblage
 npm run test:e2e      # boot réel + HTTP/WS — le gate LENT, hors `verify`
 ```
 
+Ton diff ajoute une route, une requête ou touche la sécurité ? Relis-le AVANT de commiter :
+skill `nodefony-security-review` — un script y nomme, ligne par ligne, ce qu'un œil laisse passer.
+
 Puis, en une phrase : **nomme ce que tu n'as PAS lancé.** Un vert ne couvre que le diff qui l'a
 produit, et un banc sauté faute de son décor compte comme vert. Dire « e2e non lancé » coûte
 cinq mots ; le taire coûte la confiance dans tout le reste.

package/skills/nodefony-dev/scripts/docs.mjs

@@ -21,10 +21,23 @@
  * `@output` les pages classées, avec chemin, ligne et extrait — ou un refus qui DIT pourquoi
  */
 
-import { readFileSync, readdirSync, statSync } from "node:fs";
+import { readFileSync, readdirSync, statSync, realpathSync } from "node:fs";
 import path from "node:path";
 import process from "node:process";
-import { pathToFileURL } from "node:url";
+import { fileURLToPath } from "node:url";
+import { findProjectRoot } from "nodefony/project-root";
+
+/**
+ * Racine de l'APPLICATION vue depuis `cwd` — le dossier qui porte
+ * `nodefony.config.ts` —, ou `cwd` lui-même hors application. Un script lancé
+ * depuis `frontend/` ou `modules/blog/` travaille ainsi sur l'app entière.
+ * `nodefony/project-root` est le sous-chemin LÉGER du cœur (`node:` seul) :
+ * importer `nodefony` entier coûtait jusqu'à plusieurs secondes à froid.
+ *
+ * @param {string} cwd - le dossier de lancement.
+ * @returns {string} la racine retenue.
+ */
+const appRoot = (cwd) => findProjectRoot(cwd) ?? cwd;
 
 /** Nombre de pages rendues par défaut — au-delà, personne ne lit. */
 const DEFAULT_LIMIT = 6;
@@ -55,14 +68,14 @@ const FLAGS = new Set([
  * @returns les options lues.
  * @throws Error quand un drapeau est inconnu ou qu'une valeur manque.
  */
-export function parseArgs(argv) {
+export function parseArgs(argv, cwd = process.cwd()) {
   const opts = {
     terms: [],
     list: false,
     open: /** @type {string | null} */ (null),
     json: false,
     limit: DEFAULT_LIMIT,
-    root: process.cwd(),
+    root: appRoot(cwd),
     help: false,
   };
   for (let i = 0; i < argv.length; i += 1) {
@@ -123,7 +136,7 @@ export function docDirectories(root) {
   };
   push(path.join(modules, "nodefony"));
   const scope = path.join(modules, "@nodefony");
-  let entries = [];
+  let entries;
   try {
     entries = readdirSync(scope);
   } catch {
@@ -142,7 +155,7 @@ export function docDirectories(root) {
 function markdownFiles(dir) {
   const out = [];
   const walk = (current) => {
-    let entries = [];
+    let entries;
     try {
       entries = readdirSync(current, { withFileTypes: true });
     } catch {
@@ -287,7 +300,7 @@ export function index(root) {
   const pages = [];
   for (const dir of docDirectories(root)) {
     for (const file of markdownFiles(dir)) {
-      let source = "";
+      let source;
       try {
         source = readFileSync(file, "utf8");
       } catch {
@@ -538,7 +551,10 @@ export function main() {
 // confondrait deux scripts homonymes de deux skills.
 if (
   process.argv[1] !== undefined &&
-  pathToFileURL(process.argv[1]).href === import.meta.url
+  // Chemins RÉELS des deux côtés : Node résout `import.meta.url` en suivant
+  // les liens, pas `argv[1]` — lancé par `/var/…` (macOS) ou un dossier lié,
+  // la comparaison brute échouait et le script ne faisait RIEN.
+  realpathSync(process.argv[1]) === fileURLToPath(import.meta.url)
 ) {
   process.exitCode = main();
 }