@nodefony/devkit 10.0.0-alpha.6 → 10.0.0-alpha.7

package/skills/nodefony-devops/references/kubernetes.md

@@ -0,0 +1,189 @@
+# Kubernetes — ton Deployment
+
+> **Maintenance** : vérité courante. Éditer en place.
+
+## 1. Ce qui est rendu, et ce qui ne l'est pas
+
+**Rendu à ton nom** : `deploy/migrate-job.yaml`, le travail qui joue les migrations. Son mode
+d'emploi est en tête du fichier.
+
+**Pas rendu** : le Deployment, le Service, l'Ingress, les Secret et ConfigMap. Tu les écris. Cette
+page dit quoi y mettre ; le guide `kubernetes.md` du framework en donne un exemple complet.
+
+```bash
+kubectl apply -f deploy/migrate-job.yaml     # les migrations AVANT les nouveaux exemplaires
+kubectl wait --for=condition=complete job/<nom> --timeout=300s
+kubectl apply -f <ton-deployment>.yaml
+```
+
+L'ordre n'est pas négociable : un exemplaire neuf face à un schéma ancien écrit dans des colonnes
+qui n'existent pas.
+
+## 2. Le contexte de sécurité — politique Restricted
+
+**Commence par lire `deploy/migrate-job.yaml` : son contexte de sécurité est déjà conforme.** Il
+est le seul modèle juste que tu aies sous la main, et il a été écrit pour être recopié.
+
+Six exigences, toutes portées par le **manifeste** — aucune n'est « héritée de l'image ». Ce que
+l'image apporte, c'est de les rendre satisfaisables sans contorsion : elle déclare
+`USER 1000:1000`, donc l'identifiant numérique existe ; elle n'écoute qu'au-dessus de 1024, donc
+aucune capacité n'est nécessaire. Cinq ne coûtent rien à poser. **La sixième —
+`readOnlyRootFilesystem` — demande les deux volumes**, et c'est la seule qui se travaille.
+
+```yaml
+spec:
+  securityContext:
+    runAsNonRoot: true
+    runAsUser: 1000
+    runAsGroup: 1000
+    fsGroup: 1000
+    fsGroupChangePolicy: OnRootMismatch # c'est LUI qui donne le volume au bon porteur
+    seccompProfile: { type: RuntimeDefault }
+  containers:
+    - name: <app>
+      securityContext:
+        allowPrivilegeEscalation: false
+        readOnlyRootFilesystem: true
+        capabilities: { drop: ["ALL"] }
+      volumeMounts:
+        - { name: tmp, mountPath: /app/tmp }
+        - { name: var, mountPath: /app/var }
+  volumes:
+    - { name: tmp, emptyDir: { sizeLimit: 256Mi } }
+    - { name: var, emptyDir: {} }
+```
+
+- **`seccompProfile`** : la politique traite l'**absence** de profil comme une violation, pas comme
+  un défaut permissif. Aucun coût : rien ici n'appelle de fonction système exotique.
+- **`readOnlyRootFilesystem: true`** : possible **uniquement** avec les deux volumes ci-dessus.
+  Sans eux, le conteneur ne démarre pas — l'application crée `tmp/` et `var/` au démarrage.
+
+> ⚠️ **Un volume éphémère en mémoire compte dans la limite mémoire du conteneur.** Laisse
+> `emptyDir: {}` sur disque, et pose une `sizeLimit` — un dossier temporaire sans borne est un
+> moyen de faire évincer ton propre pod.
+
+**Le rendre opposable, sinon ça ne prouve rien :**
+
+```bash
+kubectl label ns <ns> pod-security.kubernetes.io/enforce=restricted
+kubectl apply -f <ton-deployment>.yaml       # doit passer SANS avertissement
+```
+
+Puis **débranche** : retire un `emptyDir`, réapplique. Le pod ne doit plus démarrer. Une politique
+qu'on n'a jamais vue refuser quelque chose n'est pas une politique.
+
+## 3. Les sondes
+
+```yaml
+startupProbe:
+  {
+    httpGet: { path: /readyz, port: 5151 },
+    periodSeconds: 2,
+    failureThreshold: 30,
+  }
+readinessProbe: { httpGet: { path: /readyz, port: 5151 }, periodSeconds: 5 }
+livenessProbe: { httpGet: { path: /livez, port: 5151 }, periodSeconds: 10 }
+```
+
+- **Pas de sonde de démarrage dédiée côté application** : `/readyz` en fait office. Dimensionne
+  `failureThreshold × periodSeconds` sur le **pire** temps de démarrage, pas le meilleur — c'est la
+  cause n° 1 des pods qui redémarrent en boucle avec des journaux muets.
+- **`livenessProbe` sur `/livez`, jamais sur `/readyz`.** `/livez` reste à `200` pendant le drain :
+  un exemplaire qui draine est vivant. Sonder `/readyz` en vivacité le ferait **tuer** au milieu de
+  son arrêt propre — exactement ce qu'on cherche à éviter.
+- Les deux répondent **avant la limitation de débit** : un kubelet limité recevrait `429` et
+  conclurait à un échec.
+
+## 4. L'arrêt — ne perdre aucune requête
+
+```yaml
+terminationGracePeriodSeconds: 30
+lifecycle: { preStop: { sleep: { seconds: 2 } } }
+```
+
+La chronologie réelle :
+
+```
+SIGTERM ──► /readyz passe à 503 ──► le répartiteur retire le pod ──► drain ≤ 15 s ──► sortie 0
+            │                                                                          │
+            └── preStop : le temps que les points d'accès se propagent ────────────────┘
+                                          fenêtre de grâce : 30 s
+```
+
+**La fenêtre doit être strictement supérieure au drain** (15 s). À l'expiration, le kubelet tue —
+code **137**, requêtes en vol perdues, aucun message. Le `preStop` court existe parce que le
+retrait d'un point d'accès n'est pas instantané : sans lui, du trafic arrive encore après le début
+du drain.
+
+**Vérifier que ça marche** — sous charge constante, `kubectl rollout restart deploy/<app>` : zéro
+`5xx`. C'est la seule preuve qui compte.
+
+## 5. Les ressources
+
+```yaml
+resources:
+  requests: { cpu: 250m, memory: 256Mi }
+  limits: { memory: 512Mi } # PAS de limite CPU
+```
+
+**Pas de limite processeur.** Une limite mémoire tue proprement et le pod redémarre ; une limite
+processeur ne tue pas — elle **ralentit en permanence**, et ça ne ressemble pas à une limite, ça
+ressemble à une application lente. Les demandes suffisent à garantir la part.
+
+Si tu bornes le tas de la machine virtuelle JavaScript face à une limite mémoire de cgroup,
+dimensionne-le avec une mesure, pas au jugé.
+
+## 6. La base de données — elle n'est pas dans le cluster
+
+C'est la différence la plus structurante avec le compose de développement.
+
+1. **Aucun manifeste de base n'est fourni**, et c'est voulu : en production elle est administrée.
+2. **Ne reporte jamais l'hôte du compose.** `compose.yaml` pointe un **service du compose** ; le
+   même nom dans un cluster désigne un Service qui n'existe pas. Rien ne casse au déploiement, tout
+   casse au premier accès.
+3. **L'URL passe par un Secret, en `_FILE`** — elle porte un mot de passe, elle n'a rien à faire
+   dans un ConfigMap.
+4. **Le plafond de connexions.** Une base administrée les compte strictement. N exemplaires × le
+   pool de chacun peuvent la saturer, et l'erreur sort de **son** côté, pas du tien. Reste prudent
+   sur le nombre d'exemplaires.
+
+| Ta base                | Exemplaires      | Volume pour `var/`        | Stratégie       |
+| ---------------------- | ---------------- | ------------------------- | --------------- |
+| SQLite (fichier local) | **1, impératif** | revendication persistante | **`Recreate`**  |
+| Serveur (administrée)  | plusieurs        | `emptyDir`                | `RollingUpdate` |
+
+> 🔴 **SQLite impose `strategy: Recreate`.** Un déploiement progressif sur un volume monté par un
+> seul nœud attend un disque que l'exemplaire précédent tient encore : le nouveau pod reste en
+> attente **pour toujours**, sans que rien ne nomme la cause.
+
+## 7. Les variables du manifeste
+
+```yaml
+env:
+  - { name: NODE_ENV, value: production }
+  - { name: NF_POD_NAME, valueFrom: { fieldRef: { fieldPath: metadata.name } } }
+  - { name: NF__HTTP__TRUSTPROXY, value: uniquelocal }
+  - { name: NF_CSRF_SECRET_FILE, value: /run/secrets/csrf }
+  - { name: NF_DATABASE_URL_FILE, value: /run/secrets/db-url }
+```
+
+`NF_POD_NAME` vient de l'API descendante. Elle dérive l'identité d'origine du bus temps réel : sans
+elle, plusieurs exemplaires se confondent et les messages s'écoutent eux-mêmes.
+
+`NF__HTTP__TRUSTPROXY` est **obligatoire** dès qu'un Ingress termine le TLS —
+[`frontal.md`](frontal.md) dit ce qui tombe sans lui, et comment le voir tomber.
+
+## 8. Éprouver sans cluster de production
+
+```bash
+kind create cluster --name <app>
+kubectl label ns default pod-security.kubernetes.io/enforce=restricted
+kubectl apply -f deploy/migrate-job.yaml
+kubectl apply -f <ton-deployment>.yaml
+kubectl rollout status deploy/<app>
+kind delete cluster --name <app>
+```
+
+`podman kube play` joue les mêmes fichiers **sans cluster du tout** — mais il ne rejoue ni
+l'admission de la politique, ni l'Ingress, ni un déploiement progressif. Ce qu'il ne prouve pas
+doit être dit, pas supposé prouvé.

package/skills/nodefony-devops/references/podman.md

@@ -0,0 +1,103 @@
+# Podman — les six écarts avec Docker
+
+> **Maintenance** : vérité courante. Éditer en place.
+
+Podman fait tourner cette image. Six choses changent, dont **une qui ne se répare pas** — et c'est
+celle-là qu'il faut connaître avant de mettre une application derrière un frontal.
+
+## 1. Le contrôle de santé disparaît
+
+Podman construit en format OCI par défaut, et **le format OCI ne porte pas de `HEALTHCHECK`**.
+`podman inspect` rend alors une valeur vide, et toute dépendance qui attend « ce service est sain »
+ne s'arme jamais — donc l'orchestration de ton compose démarre dans le désordre, sans erreur.
+
+```bash
+podman build --format docker -t <app> .              # le garde
+podman run --health-cmd '…' --health-interval 10s …  # ou le poser à l'exécution
+```
+
+## 2. L'arrêt coupe à 10 s — sous le drain
+
+`podman stop` attend **10 secondes** par défaut. Le drain de l'application est borné à **15**.
+Chaque arrêt tue donc l'application au milieu de son drain : code **137**, requêtes en vol perdues,
+aucun message.
+
+```bash
+podman stop --time 20 <conteneur>
+# ou, dans le compose :  stop_grace_period: 20s
+```
+
+C'est l'écart le plus fréquent, et celui qui ressemble le moins à un problème de conteneur.
+
+## 3. Un montage lié n'est pas inscriptible, en mode sans privilèges
+
+En mode sans privilèges, l'identifiant `1000` **du conteneur** est projeté sur un identifiant
+subordonné **de l'hôte** — qui n'est pas ton `1000` à toi. Un dossier de ton disque monté dans le
+conteneur ne lui appartient donc pas : le premier `mkdir` de l'application échoue en `EACCES`.
+
+Deux remèdes :
+
+- **un volume nommé** — il hérite du porteur du dossier sous-jacent, que l'image a déjà fixé ;
+- **le suffixe `:U`** sur le montage, qui recale le porteur.
+
+## 4. Conserver l'identité de l'hôte écrase le `USER` de l'image
+
+`--userns=keep-id` **nu** fait tourner le processus sous l'identifiant de l'hôte, et non sous le
+`1000` que l'image déclare. Si ton identifiant d'hôte n'est pas `1000`, les dossiers `/app/tmp` et
+`/app/var` — qui appartiennent à `1000` — lui refusent l'écriture, et le démarrage meurt.
+
+```bash
+podman run --userns=keep-id:uid=1000,gid=1000 …
+```
+
+## 5. SELinux refuse les montages liés
+
+Sur une distribution avec SELinux en vigueur, un montage lié est refusé (`permission denied`) tant
+qu'il ne porte pas de suffixe de réétiquetage :
+
+```bash
+-v ./docker/db:/docker-entrypoint-initdb.d:ro,z
+```
+
+Le `z` partage l'étiquette entre conteneurs, le `Z` la rend exclusive. Sur un dossier partagé par
+plusieurs services, c'est `z`.
+
+## 6. 🔴 L'adresse du client est perdue — et ça ne se répare pas
+
+En mode sans privilèges, la redirection de ports passe par un composant qui **ne préserve pas
+l'adresse source**. Le trafic arrive donc depuis la passerelle, pas depuis le client.
+
+Conséquences, toutes **silencieuses** :
+
+- l'en-tête d'adresse d'origine porte la passerelle → **l'audit est faux** ;
+- toute limitation par adresse voit **une seule** adresse → elle protège tout le monde de personne,
+  ou bloque tout le monde ensemble ;
+- aucune erreur, aucun journal : les valeurs sont plausibles, simplement fausses.
+
+**Ce n'est pas un réglage à trouver.** Une autre pile réseau existe, mais son état varie selon les
+versions. La conduite à tenir est de l'**énoncer** — dans le README de ton déploiement, dans le
+ticket, dans la revue — et non de la masquer derrière une configuration qui en aurait l'air.
+
+## 7. Ce qui marche pareil
+
+| Point                                   | Verdict                                                                                   |
+| --------------------------------------- | ----------------------------------------------------------------------------------------- |
+| Un processus d'init dédié               | Inutile, comme avec Docker : `node` est le processus n° 1 et reçoit `SIGTERM` directement |
+| Les ports au-dessus de 1024             | `5151`, `8080`, `8443` : rien d'inaccessible en mode sans privilèges                      |
+| Racine scellée + volumes `tmp` et `var` | Identique                                                                                 |
+| `podman kube play`                      | Joue tes manifestes **sans cluster** — voir ci-dessous                                    |
+
+## 8. `podman kube play` — ce qu'il prouve, et ce qu'il ne prouve pas
+
+```bash
+podman kube play deploy/
+```
+
+**Il prouve** : que le YAML est valide, que l'image démarre avec ce contexte de sécurité, que les
+volumes déclarés suffisent, que les sondes répondent.
+
+**Il ne prouve pas** : l'admission de la politique de sécurité (aucun contrôleur d'admission), les
+Ingress, un déploiement progressif, la mise à l'échelle.
+
+C'est une preuve locale utile et bon marché. Elle ne remplace pas un cluster jetable — elle évite
+d'en démarrer un pour une faute de frappe.

package/skills/nodefony-devops/references/secrets.md

@@ -0,0 +1,108 @@
+# Secrets, mots de passe, matière cryptographique
+
+> **Maintenance** : vérité courante. Éditer en place.
+
+## 1. Le fait qui gouverne tout
+
+**Une couche d'image est lisible par quiconque télécharge l'image, et un fichier effacé par une
+couche ultérieure y reste.** Un `COPY` d'un secret suivi d'un `RUN rm` ne supprime rien : le
+secret est toujours dans l'archive, à une commande d'extraction. Un conteneur qui démarre ne le
+montre plus — c'est précisément ce qui rend l'erreur indétectable à l'œil.
+
+```bash
+npx nodefony image:check <app>     # lit les COUCHES, pas l'image aplatie. Sort en échec.
+```
+
+C'est pour ça que ce contrôle existe, et pour ça qu'il ne regarde pas l'image aplatie : un
+contrôle qui la regarderait serait **vert dans le cas exactement le plus fautif**.
+
+## 2. Ce qui n'entre jamais dans l'image — le `.dockerignore`
+
+Il est rendu avec l'application, et il exclut quatre familles. Ne les retire pas.
+
+| Famille                                 | Pourquoi                                                                                                                                  |
+| --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
+| `**/node_modules`, `**/dist`            | Reconstruits **dans** l'image. Entrés depuis ta machine, ils masqueraient la construction et l'image partirait avec le code de la veille. |
+| `var`, `logs`, `**/*.log`, `**/*.jsonl` | Écritures propres à une machine, sans valeur dans une image                                                                               |
+| `*.local`, `**/*.local`                 | La convention des fichiers de secrets locaux — jamais commités, et pas davantage dans une image                                           |
+| **La matière cryptographique**          | Clés privées, certificats                                                                                                                 |
+
+> ⚠️ **Un motif de `.dockerignore` n'obéit pas aux règles du `.gitignore`.** Sans `**/`, il est
+> **ancré à la racine du contexte** — alors qu'en `.gitignore` il vaut à toute profondeur. Un
+> `*.log` seul ne voit donc aucun journal dans un sous-dossier. Quand tu ajoutes une exclusion,
+> écris `**/motif` sauf si tu veux vraiment ne viser que la racine.
+
+## 3. Les certificats — ils se MONTENT, ils ne se gravent pas
+
+L'image du frontal ne contient **aucune** clé privée : les certificats sont montés en lecture
+seule à l'exécution. En Kubernetes, un Secret monté en volume ; avec compose, un montage lié.
+
+L'étage de construction efface aussi les certificats de développement générés localement, pour
+qu'aucun certificat auto-signé de ta machine ne descende en production.
+
+## 4. Les secrets de l'application
+
+| Variable            | Ce qu'il protège                                               | Doit être partagé entre exemplaires ?                                  |
+| ------------------- | -------------------------------------------------------------- | ---------------------------------------------------------------------- |
+| `NF_CSRF_SECRET`    | Les jetons anti-CSRF                                           | **oui** — sinon un jeton émis par un exemplaire est refusé par l'autre |
+| `NF_TOTP_KEY`       | Le chiffrement au repos des secrets de double authentification | **oui** — sinon les seconds facteurs deviennent illisibles             |
+| `NF_WEBHOOK_KEY`    | Le chiffrement des signatures de webhooks                      | **oui**                                                                |
+| `NF_ADMIN_PASSWORD` | Le compte d'administration                                     | —                                                                      |
+
+> 🔴 **Le partage entre exemplaires n'est pas un détail de confort.** Un secret différent par
+> exemplaire produit des échecs **intermittents** — une requête sur deux, selon le répartiteur.
+> C'est le symptôme le plus coûteux à diagnostiquer, parce qu'il ressemble à un problème réseau.
+
+`NF_ADMIN_PASSWORD` a un défaut en développement. **En production il est obligatoire** : sans lui,
+aucun compte d'administration n'est créé et le démarrage échoue — volontairement, plutôt que de
+créer un compte avec un mot de passe connu de tout le monde.
+
+## 5. Les monter, pas les poser en clair
+
+Le suffixe `_FILE` marche sur **toute** variable — détail complet dans
+[`variables.md`](variables.md). Ce qu'il faut retenir ici :
+
+```yaml
+# Kubernetes
+env:
+  - name: NF_CSRF_SECRET_FILE
+    value: /run/secrets/csrf
+volumeMounts:
+  - { name: secrets, mountPath: /run/secrets, readOnly: true }
+```
+
+```yaml
+# compose
+secrets: [csrf]
+environment:
+  NF_CSRF_SECRET_FILE: /run/secrets/csrf
+```
+
+**Pourquoi le fichier plutôt que la variable** : une variable d'environnement est lisible dans
+`/proc/<pid>/environ`, ressort dans `docker inspect`, dans un vidage de processus, et souvent dans
+un rapport d'erreur. Un fichier monté ne ressort d'aucun des quatre.
+
+**Poser `KEY` et `KEY_FILE` ensemble fait échouer le démarrage.** L'ambiguïté n'est pas arbitrée en
+silence — c'est voulu.
+
+## 6. Rotation
+
+Les secrets de session et de CSRF ne peuvent pas changer d'un coup sans invalider ce qui est en
+vol. L'ordre qui limite la casse :
+
+1. Poser le nouveau secret **à côté** de l'ancien dans le gestionnaire de secrets.
+2. Redéployer **progressivement** — les exemplaires reprennent le nouveau.
+3. Retirer l'ancien **après** que tous les exemplaires ont repris, pas avant.
+
+Entre 2 et 3, les deux valeurs coexistent : c'est la fenêtre où rien ne casse. Sauter l'étape 3
+est l'erreur la plus fréquente — un secret « remplacé » qui traîne encore six mois plus tard.
+
+## 7. Ce qu'il ne faut pas faire, et pourquoi c'est tentant
+
+| Tentation                                        | Ce qui arrive                                                                                        |
+| ------------------------------------------------ | ---------------------------------------------------------------------------------------------------- |
+| Mettre le secret en `ARG` de construction        | Les arguments de construction sont **dans les métadonnées de l'image**. `docker history` les montre. |
+| Copier le fichier de secrets puis l'effacer      | Il reste dans la couche. Voir §1.                                                                    |
+| Mettre les secrets dans un ConfigMap             | Un ConfigMap n'est ni chiffré au repos ni traité comme sensible par les outils                       |
+| Laisser le défaut de développement en production | Il est **connu** : il est dans le dépôt public du framework                                          |
+| Passer le secret en ligne de commande            | La ligne de commande est visible dans la liste des processus du conteneur                            |

package/skills/nodefony-devops/references/variables.md

@@ -0,0 +1,174 @@
+# Les variables d'environnement
+
+> **Maintenance** : vérité courante. Éditer en place.
+
+## 1. La commande qui répond, et à laquelle rien ne ment
+
+```bash
+npx nodefony env            # la cascade des .env, la valeur EFFECTIVE de chaque variable, et sa PROVENANCE
+npx nodefony env --json     # le même rapport, pour un script
+```
+
+C'est **la** commande d'exploitation. Elle ne dit pas ce que ton manifeste déclare : elle dit ce
+que l'application a **réellement lu**, et d'où ça vient. Toutes les fois où « la variable ne fait
+rien », la réponse est dans cette sortie.
+
+```bash
+npx nodefony inspect config --json          # la configuration effective, et la provenance de chaque valeur
+npx nodefony inspect schema <module>        # les clés qui EXISTENT, leur type, ce qu'elles font
+npx nodefony doctor --env production        # ce qui manquerait là-bas, depuis ici
+```
+
+> 🔴 **`inspect schema` avant d'écrire une clé.** Une clé inconnue n'est pas refusée : elle est
+> **retirée en silence** à la validation. Tu poses le réglage, rien ne change, rien ne le dit.
+
+## 2. Deux grammaires, et elles ne font pas la même chose
+
+### `NF_<NOM>` — les variables du catalogue
+
+Simple underscore. Ce sont des variables **déclarées**, avec un rôle, un type et un défaut connus.
+
+### `NF__<MODULE>__<CHEMIN>` — la surcharge de configuration
+
+**Double** underscore. Elle atteint **n'importe quelle clé de configuration de n'importe quel
+module**, sans que cette clé ait eu besoin d'être prévue comme variable. Le séparateur en double
+underscore est la convention .NET Core et Docker : explicite, et sans ambiguïté avec le camelCase.
+
+```bash
+NF__SECURITY__JWT__ACCESSTTLS=300
+NF__HTTP__SERVERS__HTTPS__PORT=8443
+NF__SECURITY__CORS__ORIGINS=https://a.com,https://b.com     # la virgule fait un tableau
+```
+
+- Le **premier segment est le module** (`SECURITY` → `@nodefony/security`), les suivants sont le
+  chemin dans sa configuration.
+- Les segments sont **insensibles à la casse** et résolus contre les clés réelles :
+  `ACCESSTTLS` trouve `accessTtlS`.
+- **Précédence** : appliquée **après** la configuration de l'application, et **avant** la
+  validation du schéma. Donc une valeur surchargée est **validée comme les autres** — une valeur
+  aberrante fait échouer le démarrage au lieu de s'installer.
+- Résolue **une fois au démarrage**. Aucun coût par requête.
+
+**La conversion est explicite**, pas devinée par une bibliothèque : `true`/`false` deviennent un
+booléen, un nombre devient un nombre, `[…]` et `{…}` sont lus en JSON, une chaîne à virgules
+devient un tableau, le reste reste une chaîne. C'est ce qui évite le piège classique où la chaîne
+`"false"` est convertie en booléen **vrai**.
+
+## 3. Le suffixe `_FILE` — les secrets montés
+
+**Toute** variable du catalogue accepte un `_FILE`. Le contenu du fichier est lu, retour à la ligne
+final retiré.
+
+```yaml
+env:
+  - name: NF_CSRF_SECRET_FILE
+    value: /run/secrets/csrf
+```
+
+Trois comportements à connaître, et les deux derniers sont ce qui distingue ce mécanisme d'un
+mécanisme complaisant :
+
+| Situation                                      | Ce qui se passe                                                     |
+| ---------------------------------------------- | ------------------------------------------------------------------- |
+| `KEY` absente, `KEY_FILE` pointe un fichier    | La valeur est lue dans le fichier                                   |
+| **`KEY` ET `KEY_FILE` posées toutes les deux** | **Le démarrage ÉCHOUE** — l'ambiguïté n'est pas arbitrée en silence |
+| `KEY_FILE` pointe un fichier **illisible**     | **Le démarrage ÉCHOUE** — pas de repli muet sur un défaut           |
+
+C'est délibéré : un secret qu'on croit monté et qui ne l'est pas est une application qui tourne
+avec un secret de développement, en production, sans que personne le sache.
+
+Marche avec les secrets Docker, les secrets Kubernetes, et tout agent qui dépose un fichier.
+
+## 4. Les variables de l'exploitation
+
+Les seules qui te concernent au déploiement. Le catalogue complet, c'est `npx nodefony env`.
+
+### Environnement et réseau
+
+| Variable        | Rôle                       | Absente ⇒            |
+| --------------- | -------------------------- | -------------------- |
+| `NF_ENV`        | L'environnement applicatif | Dérivé de `NODE_ENV` |
+| `NF_PORT`       | Port HTTP                  | `5151`               |
+| `NF_PORT_HTTPS` | Port HTTPS                 | `5152`               |
+
+### Derrière un frontal — **les plus importantes**
+
+| Variable                     | Rôle                                              | Absente ⇒                                                                            |
+| ---------------------------- | ------------------------------------------------- | ------------------------------------------------------------------------------------ |
+| `NF__HTTP__TRUSTPROXY`       | Quels intermédiaires sont crus sur leurs en-têtes | **Le schéma constaté est `http`** → cookie `__Host-` non émis, adresse client fausse |
+| `NF__HTTP__TRUSTEDHOSTS`     | Les hôtes servis                                  | Un `Host` étranger n'est pas refusé                                                  |
+| `NF__APP__DOMAINCHECK`       | Contrôle du domaine                               | Pas de contrôle                                                                      |
+| `NF__HTTP__STATICS__ENABLED` | L'application sert-elle les fichiers statiques    | Elle les sert — donc en double avec ton frontal                                      |
+
+### Données
+
+| Variable          | Rôle                   | Absente ⇒                                            |
+| ----------------- | ---------------------- | ---------------------------------------------------- |
+| `NF_DATABASE_URL` | L'URL de la base       | **Repli sur SQLite local**, dans `var/` — silencieux |
+| `NF_REDIS_URL`    | L'URL du cache partagé | Le cache n'est pas chargé                            |
+
+> Le repli SQLite est le piège d'exploitation classique : l'application **démarre**, sert des
+> requêtes, écrit dans un fichier — et chaque exemplaire a sa propre base. Rien n'est en erreur.
+> `npx nodefony env` le montre en une ligne.
+
+### Secrets — obligatoires en production
+
+| Variable            | Ce qu'il protège                                 |
+| ------------------- | ------------------------------------------------ |
+| `NF_CSRF_SECRET`    | Les jetons anti-CSRF, partagés entre exemplaires |
+| `NF_TOTP_KEY`       | Les secrets de double authentification au repos  |
+| `NF_WEBHOOK_KEY`    | Les signatures de webhooks                       |
+| `NF_ADMIN_PASSWORD` | Le compte d'administration                       |
+
+Tous en `_FILE` en production. Détail et rotation → [`secrets.md`](secrets.md).
+
+### Plusieurs exemplaires
+
+| Variable                          | Rôle                                                                         |
+| --------------------------------- | ---------------------------------------------------------------------------- |
+| `NF_POD_NAME`                     | Identité de l'exemplaire — **dérive l'identité d'origine du bus temps réel** |
+| `NF_INSTANCE_ID`                  | Identifiant d'exemplaire                                                     |
+| `NF_REALTIME_DRIVER`              | Le transport du bus entre exemplaires                                        |
+| `NF_REALTIME_BACKPLANE_SECRET`    | Scelle les enveloppes échangées sur le bus                                   |
+| `NF_REALTIME_BACKPLANE_NAMESPACE` | Cloisonne deux applications qui partagent le même bus                        |
+
+> 🔴 **Deux applications sur un même cache, sans espace de noms distinct, se parlent.** Le symptôme
+> est un message qui arrive à des clients d'une autre application — jamais une erreur.
+
+### Multi-process sur une seule machine
+
+| Variable     | Rôle                                                     |
+| ------------ | -------------------------------------------------------- |
+| `NF_CLUSTER` | Active le mode multi-process                             |
+| `NF_WORKERS` | Nombre d'exécutants — sinon dérivé des limites du cgroup |
+
+En Kubernetes, **laisse ça tranquille** : un exemplaire = un processus = un pod, et c'est
+l'ordonnanceur qui multiplie. Le mode multi-process sert sur une machine nue.
+
+### Démarrage et journalisation
+
+| Variable             | Rôle                                                    |
+| -------------------- | ------------------------------------------------------- |
+| `NF_BOOT_TIMEOUT_MS` | Au-delà, le démarrage abandonne — borne ta sonde dessus |
+| `NF_BOOT_WARN_MS`    | Au-delà, il avertit                                     |
+| `NF_LOG_DRIVER`      | `stdout` (défaut), `file`, ou aucun                     |
+| `NF__DEBUG`          | Débogage ciblé, par module                              |
+
+En conteneur, **laisse `NF_LOG_DRIVER` sur `stdout`** : c'est ce que ton collecteur ramasse. Écrire
+dans un fichier à l'intérieur d'un conteneur, c'est écrire dans quelque chose qui disparaît.
+
+## 5. Le préfixe `NF_` — pourquoi, et ce que ça t'évite
+
+**Tout ce que Nodefony lit est préfixé `NF_`.** Pas par coquetterie : ton environnement de
+production a déjà des `REDIS_HOST`, des `COOKIE_SECRET`, des `POD_NAME` que d'autres outils
+revendiquent. Une collision ne produit **jamais** une erreur — elle produit un comportement
+inexplicable.
+
+Deux exceptions, et deux seulement :
+
+- Ce que Nodefony ne possède pas : `NODE_ENV`, `CI`, `NODE_DEBUG`… — lues telles quelles.
+- Les alias qu'un hébergeur **pose lui-même** (`DATABASE_URL`, `REDIS_URL`, `APP_ENV`) : acceptés,
+  mais **en second rang** derrière la forme `NF_`.
+
+> ⚠️ Corollaire d'exploitation : si tu poses `REDIS_URL` **et** `NF_REDIS_URL`, c'est la forme
+> préfixée qui gagne. Purger l'une en croyant avoir purgé l'autre est une erreur déjà vue.

package/skills/nodefony-migrate-schema/SKILL.md

@@ -9,20 +9,26 @@ description: >
   exemplaires. À charger AVANT de modifier une entité déjà en base, ou avant de déployer un schéma
   changé.
   Déclencheurs : "j'ai ajouté un champ à une entité", "la colonne n'existe pas en base",
-  "modifier une table existante", "migration", "migrer le schéma", "orm:migrate", "orm:generate",
-  "la base est en retard", "appliquer les migrations", "déployer un changement de schéma",
-  "comment passer ce modèle en production", "ma base ne correspond plus au code",
-  "no such column", "column does not exist", "erreur SQL après avoir changé une entité",
-  "adopter une base existante", "réparer une migration en échec", "le pod ne devient pas prêt",
-  "comment tester ma migration", "éprouver une migration", "vérifier qu'une migration marche",
-  "prouver que ma migration s'applique", "essayer sans casser ma base", "base d'essai",
-  "rejouer les migrations depuis zéro", "repartir d'une base propre".
+  "modifier une table existante", "migrer le schéma", "orm:migrate", "orm:generate",
+  "appliquer les migrations", "déployer un changement de schéma", "no such column",
+  "column does not exist", "ma base ne correspond plus au code", "adopter une base existante",
+  "réparer une migration en échec", "éprouver une migration sans casser ma base",
+  "rejouer les migrations depuis zéro".
 metadata:
   version: 2
 ---
 
 # Faire évoluer un schéma, et le porter en production
 
+> 🧭 **Tu es arrivé ici directement ? Charge aussi `nodefony-dev`** — il porte la conduite
+> commune (par où commencer, comment prouver que c'est fait) et les pièges qui coûtent une heure,
+> serveur comme front. Cette page-ci ne couvre QUE son geste.
+>
+> Et si une réponse te manque, elle est probablement INSTALLÉE : `rg` ne descend pas dans
+> `node_modules`, donc 70 pages de documentation y paraissent absentes. Une commande les lit, avec
+> la ligne exacte :
+> `node node_modules/@nodefony/devkit/skills/nodefony-dev/scripts/docs.mjs <termes>`.
+
 ## 1. La seule chose à savoir avant tout le reste
 
 **En développement, il n'y a rien à faire.** La base suit le code : la table naît au démarrage, et
@@ -139,15 +145,21 @@ npx nodefony orm:migrate
 d'appliquer ». Il ne refuse pas — il ne lit pas la base et ignore si ta table porte des lignes —,
 mais s'il le signale et que ta table n'est pas vide, la migration échouera.
 
-**À l'étape 3, sur sqlite, attends-toi à un refus `NF_GENERATE_DESTRUCTIVE`** — mesuré sur une
-table de deux lignes. Rendre une colonne obligatoire n'est pas un `ALTER` en sqlite : le moteur
-n'en a pas, alors l'outil RECONSTRUIT la table (`CREATE __new_billets` → `INSERT … SELECT` →
-`DROP TABLE` → `RENAME`). Le `DROP TABLE` est reconnu comme destructeur, et il l'est en général —
-ici il porte sur une table déjà recopiée, une ligne plus haut, dans la même migration. **Relis le
-fichier avant de décider** : si tu y vois l'`INSERT INTO __new_… SELECT … FROM …` juste avant le
-`DROP`, la reconstruction conserve les lignes, et `orm:migrate` l'applique sans broncher (les
-fichiers sont écrits, c'est leur mise en service qui était refusée). Éprouvé de bout en bout :
-deux lignes semées, trois étapes, deux lignes intactes et l'index unique en place.
+**À l'étape 3, sur sqlite, attends-toi à un AVERTISSEMENT `table-rebuild`, pas à un refus.**
+Rendre une colonne obligatoire n'est pas un `ALTER` en sqlite : le moteur n'en a pas, alors la
+table est RECONSTRUITE (`CREATE` une table d'étape → `INSERT … SELECT` → `DROP TABLE` →
+`RENAME`). Ce `DROP TABLE` porte sur une table recopiée une ligne plus haut, dans la même
+migration : l'outil le reconnaît et te le signale — « recrée la table pour modifier une colonne
+(SQLite ne sait pas faire autrement) » — sans rien refuser, à la génération comme à la mise en
+service. Tu n'as donc **pas** besoin de `--allow-destructive` pour une reconstruction.
+
+Ce qui reste à TA charge, et c'est le sens de l'avertissement : **relis l'`INSERT … SELECT`**.
+Une colonne absente de cette recopie serait bel et bien perdue, et aucun automate ne peut le
+deviner à ta place. Éprouvé de bout en bout : deux lignes semées, trois étapes, deux lignes
+intactes et l'index unique en place.
+
+> Un vrai `DROP TABLE` — une table supprimée sans recopie, ou une AUTRE table supprimée dans la
+> même migration — reste refusé. Le verdict porte sur chaque table, pas sur le fichier.
 
 > **Ne jamais** répondre à un échec de migration en refaisant la base. Une migration qui n'est pas
 > passée n'a **rien** changé — sqlite et PostgreSQL l'annulent entière. C'est le fichier qu'il faut