nodefony 7.0.2 → 10.0.0-alpha.2

package/templates/app/agents/POINTEUR.md.tpl

@@ -0,0 +1,12 @@
+# <%= it.pointeur %>
+
+> **Lis `AGENTS.md`** — les instructions agent de cette application vivent
+> là-bas (standard **Agentic AI Foundation** / Linux Foundation, précédence
+> « le plus proche gagne »). <%= it.agents %> ne le lit pas d'office : ce
+> fichier n'est qu'un pointeur, et ce qu'on y recopierait divergerait en
+> silence.
+>
+> Deux réflexes gouvernent les autres, et `AGENTS.md` les détaille : **avant
+> d'écrire un fichier, vérifie qu'un générateur ne le produit pas**
+> (`npx nodefony create --help`) — et **avant de dire « fait »,
+> `npm run verify`** : un `npm test` vert ne typecheck RIEN.

package/templates/app/base/Dockerfile.tpl

@@ -0,0 +1,104 @@
+# syntax=docker/dockerfile:1
+# ─────────────────────────────────────────────────────────────────────────────
+# Image de <%= it.appName %> — Nodefony, doctrine cloud-native.
+#
+# 1 process = 1 container. La montée en charge se fait par RÉPLIQUES de
+# l'orchestrateur (k8s, Swarm, Nomad, Cloud Run, Fargate), jamais par un
+# gestionnaire de process dans l'image.
+#
+# Le container DIALOGUE avec l'orchestrateur par SIGTERM (`docker stop`,
+# éviction k8s) : le framework draine — `/readyz` passe en 503, les sockets
+# ferment en 1001, les requêtes en vol vont à leur terme, puis exit 0 — sous
+# `shutdownDeadline` (15 s par défaut). Garder la période de grâce AU-DESSUS :
+# k8s donne 30 s, `docker stop` 10 s (`-t 20` pour être large).
+# ─────────────────────────────────────────────────────────────────────────────
+
+# ── Étape de construction : la chaîne de compilation ne descend PAS en prod ───
+FROM node:24-slim AS build
+WORKDIR /app
+
+# Les sources d'ABORD, en un seul geste — et non le manifeste seul comme le
+# veut l'usage. Une dépendance d'application Nodefony peut être LOCALE : les
+# workspaces `modules/*` que pose `nodefony create module`, ou une archive
+# `file:` avant publication. Installer avant de les avoir copiées échouerait
+# sur elles. Ce qui ne doit pas entrer est listé dans `.dockerignore` — c'est
+# lui qui tient les secrets (`*.local`) et le `dist/` de la machine dehors.
+COPY . ./
+
+# Le cache npm est monté plutôt que gravé : la couche est invalidée dès qu'une
+# source change, mais les paquets déjà téléchargés ne le sont pas. On garde
+# donc une installation VIERGE, sans la repayer en réseau à chaque build.
+#
+# 🔴 `--ignore-scripts` n'est PAS une précaution de confort — sans lui, cette
+# image ne se construit pas dès que le dépôt porte un `package-lock.json`,
+# c'est-à-dire dès le premier `npm install` du développeur. La cause est un
+# défaut de npm, ouvert en amont : `npm/cli#9837`, dont le correctif proposé
+# est `npm/cli#9859`. `better-sqlite3` (tiré par `@nodefony/drizzle`)
+# embarque ses binaires prébâtis et pose `gypfile: false` pour interdire à npm
+# de SYNTHÉTISER un `install: node-gyp rebuild` à la vue de son `binding.gyp`.
+# Or ce refus n'est lu que sur un arbre bâti depuis le registre : un nœud venu
+# d'un LOCKFILE ne porte pas le champ, donc npm invente le script — et le
+# paquet se fait recompiler contre sa volonté.
+#
+# Mesuré dans `node:24-slim` : SANS verrou, aucun script et aucun message ;
+# AVEC verrou, npm 11.16 exécute `node-gyp rebuild`, qui meurt faute de Python
+# et de chaîne de compilation. npm 12 le refuserait — sa politique
+# `allowScripts` BLOQUE un script non approuvé, là où celle de npm 11 se
+# contente d'avertir — mais c'est npm 11.16 que `node:24-slim` embarque.
+#
+# Le sauter est de toute façon ce qu'il faut faire : les paquets natifs d'une
+# application Nodefony embarquent leurs binaires prébâtis (vérifié —
+# `better-sqlite3` ouvre et interroge une base après une installation sans
+# scripts). Et c'est un durcissement : un script d'installation est le vecteur
+# des compromissions de chaîne d'approvisionnement, et une image de production
+# n'a aucune raison d'en exécuter.
+RUN --mount=type=cache,target=/root/.npm npm install --ignore-scripts --no-audit --no-fund
+
+# Le build passe par le script de l'application (`rolldown`, plus le build du
+# frontend quand il y en a un) : ce Dockerfile n'a donc jamais à connaître la
+# forme de la compilation. `prune` retire ensuite ce qui n'est que du
+# développement — la toolchain a fini son travail.
+#
+# ⚠️ Une application à FRONTEND garde malgré tout Vite : son plugin est une
+# devDependency, et `prune` ne retire pas ce qui satisfait la dépendance de
+# pair (optionnelle) d'un paquet de production. Refaire l'arbre depuis zéro
+# n'y change rien — le `package-lock.json` l'a figé, et c'est mesuré : 161 Mo
+# dans les deux cas. Le jour où cela se corrige, ce sera en amont, dans la
+# façon dont `@nodefony/frontend` déclare Vite.
+RUN npm run build && npm prune --omit=dev
+
+# ── Étape d'exécution : minimale, non-root ───────────────────────────────────
+FROM node:24-slim
+ENV NODE_ENV=production
+WORKDIR /app
+
+# `/app` doit appartenir à `node` : le démarrage écrit (tmp/, journaux, var/).
+RUN chown node:node /app
+
+# Un seul COPY, et c'est délibéré : il emporte `dist/`, les `node_modules`
+# élagués, les assets du frontend et les workspaces `modules/*` — dont
+# l'existence n'est pas connue au moment où ce fichier est généré. Nommer les
+# chemins un à un ferait échouer la construction sur le premier dossier absent.
+COPY --from=build --chown=node:node /app ./
+
+# Jamais root : les ports de Nodefony (5151, 5152) n'exigent aucun privilège.
+USER node
+EXPOSE 5151
+
+# Sonde de Docker / compose / Swarm sur `/readyz`, la route native du framework.
+# ⚠️ k8s IGNORE HEALTHCHECK : y déclarer `livenessProbe: /livez` (le process
+# est-il vivant ?) et `readinessProbe: /readyz` (peut-il recevoir du trafic ?).
+# ⚠️ PODMAN construit en format OCI par défaut, et l'OCI ne porte PAS cette
+# directive : la sonde est retirée de l'image SANS erreur (`podman inspect
+# --format '{{.HealthCheck}}'` rend alors `<nil>`). Constaté, avec son remède :
+#   podman build --format docker -t <image> .
+# Le reste passe tel quel sous Podman — cache monté, forme exec, node en PID 1,
+# arrêt gracieux en 0.
+HEALTHCHECK --interval=10s --timeout=2s --start-period=20s --retries=3 \
+  CMD ["node", "-e", "fetch('http://127.0.0.1:5151/readyz').then(r=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))"]
+
+# Forme EXEC obligatoire : `node` devient PID 1 et reçoit le SIGTERM. En forme
+# shell (`CMD npx nodefony production`), c'est `/bin/sh` qui est PID 1 — il ne
+# transmet pas les signaux, donc plus aucun arrêt gracieux et un SIGKILL à
+# chaque déploiement. L'image marcherait, et rien ne signalerait la perte.
+CMD ["node_modules/.bin/nodefony", "production"]

package/templates/app/base/README.md.tpl

@@ -0,0 +1,314 @@
+# <%= it.appName %>
+
+Application [Nodefony](https://github.com/nodefony/nodefony-core) — générée par `nodefony create app`.
+
+<% if (it.complete) { %>Cette app n'est pas un « hello world » : c'est le **framework complet, câblé et
+prouvé** — HTTP + WebSocket dans le même controller, ORM avec persistance
+out-of-the-box, firewall applicatif, temps réel, console d'administration,
+tests, lint, infra docker. Chaque fichier est commenté : lis-les, ils expliquent
+le POURQUOI, pas juste le quoi.
+<% } else { %>App **minimale** : le socle serveur (`@nodefony/http`) + le router et les
+controllers (`@nodefony/framework`)<% if (it.front) { %> + le frontend <%= it.frontend %> servi par Vite<% } %> — la
+base saine, à faire grandir. Pour la vitrine complète (ORM, firewall, realtime,
+Studio, infra docker) : régénère avec `--preset complete`.
+<% } %>
+---
+
+## 1. Démarrage express (60 secondes)
+
+```bash
+npm install
+npm run build        # bundle rolldown → dist/
+npm run dev          # serveur de développement
+```
+
+Puis :
+
+- http://127.0.0.1:5151/api/hello — ta première route
+<% if (it.front) { %>- http://127.0.0.1:5151/ — ton app <%= it.frontend %> (HMR Vite en dev)
+<% } %><% if (it.complete) { %>- http://127.0.0.1:5151/nodefony — **Studio**, la console d'administration (dev)
+
+> L'app **persiste déjà** : sans aucune base déclarée, l'ORM Drizzle crée une
+> sqlite locale (`var/databases/`) — users, sessions et jetons y survivent aux
+> redémarrages. Aucun service externe requis pour commencer.
+<% } %>
+## 2. Visite guidée — ce que l'app démontre
+
+- **Route HTTP** — `curl http://127.0.0.1:5151/api/hello`
+- **WebSocket, _même controller_** — `npx wscat -c ws://127.0.0.1:5151/api/echo` puis tape un message
+<% if (it.front) { %>- **Frontend <%= it.frontend %> (Vite + HMR)** — http://127.0.0.1:5151/ — l'app fetch le backend via `/api`
+<% } %><% if (it.complete) { %>- **Studio (console admin, dev)** — http://127.0.0.1:5151/nodefony — config, sessions, logs, routes
+- **ORM + persistance** — Drizzle : sans `NF_DATABASE_URL`, sqlite locale automatique
+- **Firewall + audit** — chaque requête traverse le pipeline sécurité (logs `audit`)
+- **Temps réel — socket Nodefony** — `nodefony/controllers/LiveController.ts` : canal `live:events` (alimenté par `live:say`, jamais par une horloge) + RPC `live:ping`<% if (it.front) { %> — la carte « Temps réel » de la page d'accueil le consomme par la façade client<% } %>
+- **Redis (opt-in)** — `NF_REDIS_URL` présente ⇔ module chargé, stores basculent dessus
+<% } %>- **Probes cloud-native** — `curl http://127.0.0.1:5151/livez` (liveness k8s)
+
+Le différenciateur Nodefony tient dans `nodefony/controllers/HelloController.ts` :
+**une route GET et une route WEBSOCKET dans la même classe** — même pipeline,
+pas deux mondes séparés.
+
+## 3. Structure du projet
+
+- `nodefony.config.ts` — LA config de l'app : uniquement les ÉCARTS aux défauts du framework
+- `env.ts` — catalogue **typé** des variables d'environnement (seul lecteur de `process.env`, validé au boot)
+- `index.ts` — point d'entrée : la classe `App` (module racine) + ses controllers<% if (it.front) { %> + l'entry frontend (`registerEntry`)<% } %>
+- `nodefony/controllers/` — tes controllers (`@controller` + `@route`, HTTP **et** WS)
+<% if (it.front) { %>- `frontend/src/` — ton app <%= it.frontend %>, servie par Vite (HMR dev, build prod)
+<% } %>- `tests/` — tests vitest : unitaires (`npm test`) + e2e réel (`npm run test:e2e`)
+- `AGENTS.md` — instructions pour un agent IA, 100 % généré (régénéré par `create`) ; tes notes vivent dans sa zone préservée
+<% if (it.complete) { %>- `compose.yaml` — infra de dev docker : Redis<% if (it.db) { %>, <%= it.db.label %><% } %>, Loki/Grafana (profil)
+<% } %>- `rolldown.config.ts` — build : 3 lignes, délègue tout au socle publié `nodefony/bundler`
+- `.oxlintrc.json` — lint non-intrusif (warn) ; le style est délégué à Prettier
+- `vitest.config.ts` — tests unitaires ; porte le bloc `oxc` décorateurs (OBLIGATOIRE, commenté)
+- `vitest.e2e.config.ts` — tests e2e, config séparée : `npm test` ne montre que ce qu'il exécute
+- `var/` — données locales (sqlite, logs fichiers), gitignoré
+<% if (it.complete) { %>
+## 4. Infra de développement (docker)
+
+<% if (it.db) { %>Tu as retenu **<%= it.db.label %>** à la création : le `compose.yaml` ne porte que
+ce service (plus Redis), et `.env` déclare déjà `NF_DATABASE_URL` dessus. Lance
+l'infra **avant** l'app :
+
+```bash
+npm run infra:up     # docker : Redis + <%= it.db.label %> (le compose ne porte qu'eux)
+npm run dev
+npm run infra:down   # arrêt (les volumes survivent)
+```
+
+Redis n'est utilisé que si `NF_REDIS_URL` est déclarée — sinon l'app reste en
+mémoire de process, ce qui suffit tant qu'elle tourne en un seul exemplaire :
+
+```bash
+NF_REDIS_URL="redis://:<%= it.appName %>-dev@127.0.0.1:6379"   # dans .env
+```
+
+Repasser en **sqlite locale** : commente `NF_DATABASE_URL` dans `.env`, rien
+d'autre. Le dialecte SQL est déduit du **scheme de l'URL** (`postgres://`,
+`mysql://`, `sqlite:`) — changer de base ne change **rien d'autre** dans l'app.
+Les mots de passe par défaut du compose sont publics, pour le dev local uniquement.
+<% } else { %>L'app démarre **sans docker** : la base est une **sqlite locale** (`var/databases/`),
+retenue à la création. Le `compose.yaml` fournit le cran au-dessus :
+
+```bash
+npm run infra:up                          # Redis (sessions partagées, realtime multi-process)
+docker compose --profile loki up -d       # + Loki + Grafana (logs centralisés)
+npm run infra:down                        # arrêt (les volumes survivent)
+```
+
+Câblage côté app — une variable, tout le reste se dérive (`store: "auto"`) :
+
+```bash
+NF_REDIS_URL="redis://:<%= it.appName %>-dev@127.0.0.1:6379"   # dans .env
+```
+
+Pour passer sur une vraie base SQL : déclare `NF_DATABASE_URL`. Le dialecte est
+déduit du **scheme de l'URL** (`postgres://`, `mysql://`, `sqlite:`) — changer de
+base ne change **rien d'autre** dans l'app. Le service docker correspondant n'est
+pas dans ce `compose.yaml` (une app y retient un seul dialecte) : ajoute-le, ou
+recrée une app avec `nodefony create app <nom> --database postgres`.
+<% } %><% } %>
+## 5. Tests — `npm test` est ton PREMIER diagnostic
+
+```bash
+npm test             # unitaires : l'app se CHARGE (imports, décorateurs, config) — < 1 s
+npm run test:e2e     # build + boot RÉEL (production --detach --wait) + HTTP + WS + probes
+```
+
+<% if (it.db) { %>> **Les e2e ont besoin de DEUX bases de plus**, sur ton serveur
+> <%= it.db.label %> : `<%= it.db.databaseE2e %>` (la suite ne touche jamais
+> celle du développement) et `<%= it.db.databaseScratch %>` (la base vierge que
+> la suite de migrations salit puis remet à zéro). Le compose les crée à sa
+> PREMIÈRE initialisation — sur une infra déjà montée, `docker compose down -v`
+> les fera naître, ou crée-les à la main. Elles ne se fabriquent pas toutes
+> seules au moment des tests : `CREATE DATABASE` est un privilège
+> d'administration, que ton compte applicatif n'a pas — et ne doit pas avoir.
+
+<% } %>**Réflexe** : quelque chose semble cassé → `npm test` AVANT de relire du code ou
+de redémarrer. En une seconde il prouve que l'app s'importe, que les décorateurs
+compilent et que la config valide — ou te donne le fichier exact qui casse.
+
+Le rapport est **franc** : les e2e ont leur propre config (`vitest.e2e.config.ts`),
+`npm test` n'affiche jamais de tests « skipped » qui semblent verts sans avoir
+rien prouvé. Le test e2e utilise le lancement détaché natif du framework :
+`--wait` ne rend la main que quand la readiness est sondée (aucun `sleep`
+arbitraire), et `nodefony stop` arrête proprement. Le client WebSocket est le
+`WebSocket` **natif** de Node — zéro dépendance de test.
+
+## 6. Qualité du code
+
+```bash
+npm run typecheck    # tsgo — le bundler ne type-check PAS : gate séparé, obligatoire
+npm run doctor        # cohérence du projet : config, modules déclarés, wiring
+npm run lint         # oxlint — garde-fous en warn, non-intrusif
+npm run format       # prettier — le style, c'est lui qui décide
+```
+
+Le lint et le typecheck sont **deux gates distincts**, et c'est volontaire :
+`tsgo` juge les TYPES, `oxlint` juge tout ce qu'un type ne dit pas — code mort,
+promesse mal formée, import Node sans son préfixe. Aucun des deux ne remplace
+l'autre.
+
+`oxlint` s'appuie sur le même analyseur que le bundler (`rolldown`) : un seul
+lecteur de ta syntaxe, donc aucun risque que l'un accepte ce que l'autre refuse.
+Il n'a **pas** besoin du paquet `typescript` — celui-ci ne reste dans les
+dépendances que pour ton éditeur.
+
+Les règles sont dans `.oxlintrc.json`, commentées par leur intention. Deux
+familles ne pardonnent pas : le code mort (il finit par mentir) et le préfixe
+`node:` sur les modules du runtime (sans lui, un paquet npm homonyme peut prendre
+la place d'un module natif). Le reste avertit sans bloquer.
+
+## 7. Quand ça casse (troubleshooting)
+
+Dans l'ordre — chaque étape isole un étage, du moins cher au plus cher :
+
+1. **`npm test`** — l'app se charge-t-elle ? Import cassé, décorateur, config
+   invalide : le fichier fautif est nommé.
+2. **`npm run typecheck`** — un vert vitest ne type-check RIEN (les types sont
+   effacés à la transpilation) ; `tsgo` attrape ce que le build laisse passer.
+3. **`npx nodefony status`** — un serveur tourne-t-il déjà ? (port occupé,
+   vieux process détaché). `npx nodefony stop` arrête proprement. Si le port est
+   tenu par une AUTRE application Nodefony, `status` la nomme :
+   `npx nodefony stop <nom>` l'arrête sans changer de dossier.
+4. **Rebuild** — comportement fantôme après un gros changement : `npm run build`
+   puis relance (le serveur charge `dist/`, pas tes sources).
+<% if (it.complete) { %>
+### `npm install` s'arrête sur « gyp ERR! find Python »
+
+Ton manifeste porte ceci, et il faut l'y laisser :
+
+```json
+"allowScripts": { "better-sqlite3": false }
+```
+
+`better-sqlite3` (le pilote SQLite, tiré par `@nodefony/drizzle`) livre ses
+binaires **déjà compilés** et demande à npm de ne pas le recompiler. npm oublie
+cette demande dès qu'un `package-lock.json` existe — donc dès ton premier
+`npm install` — et lance alors `node-gyp rebuild`, qui exige Python et un
+compilateur C++ ([npm/cli#9837](https://github.com/npm/cli/issues/9837)). La
+ligne ci-dessus le lui interdit explicitement, ce qu'il respecte dans toutes
+les versions.
+
+Si tu l'as retirée et que l'installation casse : remets-la, supprime
+`node_modules`, relance `npm install`. Rien à compiler, SQLite fonctionne.
+<% } %>
+## 8. Production (cloud-native)
+
+```bash
+npm run build        # backend (rolldown)<% if (it.front) { %> + frontend (vite → public/dist, fingerprinté)<% } %>
+npm start            # nodefony production — bind 0.0.0.0, logs stdout, probes /livez /readyz
+```
+<% if (it.front) { %>
+> Le front de production est un build Vite figé (`public/dist/`), servi en
+> statics par Nodefony — `npm run build` le produit (il chaîne
+> `nodefony frontend:build`). Si tu lances `npm start` sans build, le boot le
+> construit une fois pour toi quand Vite est installé (poste de dev) et le DIT
+> dans les logs ; dans une image de production sans devDependencies, builde à
+> l'image — sinon la page est servie sans interface et le boot le signale en
+> ERROR.
+<% } %>
+### Image de container
+
+`Dockerfile` et `.dockerignore` sont générés avec l'app ; la doctrine y est
+commentée ligne à ligne (multi-stage, `USER node`, sonde sur `/readyz`, forme
+exec du `CMD`).
+
+```bash
+docker build -t <%= it.appName %> .
+docker run -p 5151:5151 <%= it.appName %>
+docker stop -t 20 <container>   # SIGTERM → drain → exit 0
+```
+
+> ⚠️ **La période de grâce doit rester au-dessus de `shutdownDeadline`** (15 s
+> par défaut) : `docker stop` n'attend que 10 s sans `-t`, et k8s 30 s. En
+> dessous, le drain est coupé par un SIGKILL et les requêtes en vol meurent —
+> sans erreur ni trace, à chaque déploiement.
+
+#### Si tu PUBLIES cette image
+
+L'image emporte `node_modules` élagué : la **publier** — sur un registre public,
+ou en la livrant à un tiers — te rend distributeur du code de tes dépendances.
+MIT, BSD, ISC et Apache-2.0 demandent alors que leur texte et leur copyright
+accompagnent le code. C'est déjà le cas matériellement : chaque paquet porte son
+propre fichier de licence dans `node_modules`, et l'image les emporte avec lui.
+
+Ce qui manque, c'est l'inventaire — npm le produit sans rien installer :
+
+```bash
+npm sbom --sbom-format spdx --omit=dev > sbom.spdx.json
+```
+
+> Un **déploiement interne** (ton propre registre, ton cluster) n'est pas une
+> distribution : ces obligations ne s'y appliquent pas. Et un inventaire écrit à
+> la main serait faux dès le premier `npm install` — c'est pourquoi il se
+> régénère plutôt qu'il ne se commite.
+
+<% if (it.db) { %>### Migrations de schéma
+
+En développement, la base **suit le code** : les tables naissent au démarrage et
+un champ facultatif ajouté est posé au boot suivant. Rien de tout cela n'a lieu
+en production — le schéma s'y applique par des **migrations**, avant que le
+premier exemplaire ne démarre.
+
+Cette application **naît avec sa première migration**, sous `migrations/` : celle
+qui crée sa table `User`. Elle est écrite à la création et entre dans le premier
+commit, comme le lockfile — le schéma appartient au dépôt, jamais au
+déploiement. Deux conséquences pratiques :
+
+- **Si l'application a été créée sans installation** (`--no-install`, ou un build
+  en échec), la migration n'a pas pu être écrite : lance
+  `npx nodefony orm:generate --name init` avant ton premier déploiement, sinon
+  rien ne créera la table et les exemplaires resteront en 503.
+- **On n'écrit pas de migration en production** : `drizzle-kit` est une
+  dépendance de développement, absente de l'image. Générer se fait ici,
+  appliquer se fait là-bas.
+
+```bash
+npx nodefony orm:generate            # écrit les migrations des entités modifiées
+npx nodefony orm:migrate --dry-run   # ce qui serait appliqué, sans rien écrire
+npx nodefony orm:migrate             # applique (verrou + historique)
+npx nodefony orm:migrate:status      # 0 = à jour · 1 = en retard — ta barrière de déploiement
+```
+
+`deploy/migrate-job.yaml` est le **travail Kubernetes** correspondant, déjà rendu
+au nom de cette application : même image que le Deployment, secret DDL séparé du
+compte qui sert le trafic, mode d'emploi en tête de fichier. Sans orchestrateur
+(un seul exemplaire), `ddl: "migrate"` dans la config du connecteur applique les
+migrations au démarrage — c'est le seul cas où c'est sûr.
+
+> Les pods démarrent sans jamais fabriquer le schéma : un exemplaire dont la base
+> est en retard répond **503 sur `/readyz`** (jamais sur `/livez`) et reste hors
+> du répartiteur de charge, l'ancienne version continuant de servir. Lance le
+> travail de migration : les pods deviennent disponibles **seuls**.
+
+Le détail — droits SQL des deux comptes, règle N-1, dérive d'un schéma modifié à
+la main : `node_modules/@nodefony/drizzle/docs/migrations.md`.
+
+<% } %>Un process Node = un pod/container ; le scaling horizontal vient de
+l'orchestrateur (k8s, Swarm, Cloud Run…).<% if (it.complete) { %> Studio est chargé en dev seulement
+(`policy: "dev"`) — pour l'exposer en production, protège `/nodefony` par une
+zone firewall puis passe la policy à `"mandatory"` (la recette est commentée
+dans `nodefony.config.ts`).<% } %>
+
+## 9. Développer le framework lui-même (`--link`)
+
+Si cette app a été générée avec `--link`, les dépendances `nodefony`/`@nodefony/*`
+pointent en `file:` vers un checkout local de `nodefony-core` : tu modifies le
+framework, tu rebuilds le checkout, ton app le voit. Ne publie pas ce
+`package.json` tel quel — après la release npm, régénère sans `--link`
+(versions `^<%= it.nodefonyVersion %>`).
+
+## 10. Aller plus loin
+
+- **Ajouter une route** : une méthode décorée `@route` dans un controller — c'est tout.
+- **Régénérer autrement** : `nodefony create app` (interactif) ou
+  `--preset <complete|minimal> --frontend <none|react|vue|angular|svelte>`
+  `--database <sqlite|postgres|mariadb|mysql>` (scriptable).
+<% if (it.complete) { %>- **Protéger une zone** : `use("@nodefony/security", { firewalls: { … } })` dans
+  `nodefony.config.ts` (validée Zod au boot, config invalide = échec franc).
+- **Canaux temps réel** : le module realtime multiplexe N canaux duplex sur une
+  seule socket — voir la doc du framework.
+- **Studio** est ta carte du territoire : modules chargés, routes, config
+  résolue, sessions, logs — tout ce que le framework sait, il te le montre.
+<% } %>

package/templates/app/base/dockerignore.tpl

@@ -0,0 +1,28 @@
+# Ce qui n'entre PAS dans le contexte de construction de l'image.
+# Motifs relatifs à la racine du contexte — `**/` pour atteindre les modules
+# locaux (`modules/*/node_modules`, `modules/*/dist`).
+
+# Reconstruits DANS l'image. Entrés depuis la machine, ils masqueraient le
+# build de l'étape et l'image partirait avec le code de la veille.
+**/node_modules
+**/dist
+
+# Écritures du runtime (journaux, pid, sockets) — propres à une machine.
+var
+*.log
+
+# Secrets — convention B : `*.local` n'est jamais commité, et n'entre pas
+# davantage dans une image. Les couches d'une image sont lisibles par qui la
+# télécharge, et un secret y reste même effacé par une couche suivante. En
+# production, les valeurs viennent de l'orchestrateur (variables
+# d'environnement, gestionnaire de secrets).
+*.local
+**/*.local
+
+# Bruit — sans effet sur l'exécution, mais chaque octet du contexte est envoyé
+# au démon Docker à chaque construction.
+.git
+.gitignore
+Dockerfile
+.dockerignore
+.DS_Store

package/templates/app/base/env.ts.tpl

@@ -0,0 +1,130 @@
+import { defineEnv, envEnum, envNumber<% if (it.complete || it.front) { %>, envString<% } %> } from "nodefony";
+
+/**
+ * Catalogue typé des variables d'environnement — SEUL lecteur de `process.env`.
+ * Validé au boot (fail-fast), exposé au descripteur de config via `ctx.env`.
+<% if (it.complete) { %> *
+ * 💾 PERSISTANCE (infra déclarée) : tu déclares une ou deux URLs, le framework
+ * DÉRIVE les stores (users, sessions, jetons, idempotence…) — `store: "auto"`.
+<% } %> */
+export const env = defineEnv({
+  /**
+   * Port d'écoute HTTP. Absent = défaut du framework (5151). Le déclarer est le
+   * cas du DÉPLOIEMENT : le port y est un contrat (service k8s, ingress, sonde).
+   * En dev, ne rien mettre : si 5151 est déjà pris (une autre app Nodefony),
+   * le framework prend le port libre suivant et l'ANNONCE (`portPolicy: "auto"`,
+   * défaut hors production) — en production il échoue franchement (`strict`),
+   * car un pod qui écoute ailleurs en silence est un pod injoignable.
+   */
+  NF_PORT: envNumber({
+    optional: true,
+    description: "Port d'écoute HTTP (défaut framework 5151).",
+  }),
+
+  /**
+   * Alias PLATEFORME : Cloud Run, Heroku, Railway et Fly injectent `PORT` et
+   * exigent que le process écoute dessus. On l'accepte tel quel — zéro glue de
+   * déploiement. `NF_PORT` l'emporte si les deux sont présents.
+   */
+  PORT: envNumber({
+    optional: true,
+    description:
+      "Alias plateforme du port HTTP (Cloud Run/Heroku) — NF_PORT gagne.",
+  }),
+
+  /**
+   * Port d'écoute HTTPS/HTTP2 (défaut framework 5152). Pas d'alias plateforme :
+   * en cloud, le TLS est terminé à l'ingress et le pod sert en clair.
+   */
+  NF_PORT_HTTPS: envNumber({
+    optional: true,
+    description: "Port d'écoute HTTPS/HTTP2 (défaut framework 5152).",
+  }),
+
+  NF_LOG_DRIVER: envEnum(["stdout", "file", "null"] as const, {
+    default: "stdout",
+  }),
+<% if (it.complete) { %>
+  /**
+   * Infra `database` : URL unique, dialecte déduit du scheme
+   * (`sqlite:./var/app.db` | `postgres://…` | `mysql://…` | `mongodb://…`).
+   * ABSENTE = profil solo : sqlite local (l'app persiste quand même).
+   * Alias plateforme accepté : `DATABASE_URL`. Secret → jamais loggée brute.
+   */
+  NF_DATABASE_URL: envString({
+    optional: true,
+    description:
+      "Infra database : URL unique (sqlite:|postgres://|mysql://|mongodb://), dialecte déduit du scheme.",
+  }),
+
+  /**
+   * Infra `cache` (éphémère partagé) : URL Redis. Sa présence CHARGE le module
+   * `@nodefony/redis` et aiguille les briques éphémères (sessions, idempotence)
+   * vers Redis. Alias plateforme accepté : `REDIS_URL`.
+   */
+  NF_REDIS_URL: envString({
+    optional: true,
+    description:
+      "Infra cache : URL Redis (redis://…) — sa présence charge @nodefony/redis.",
+  }),
+
+  /**
+   * 🔐 Clés de chiffrement au repos (module security) — les VALEURS vivent dans
+   * `.env.local` (gitignoré), générées à la création de l'app. Rotation ou
+   * rattrapage : `npx nodefony security:secrets --write`. En production :
+   * Secret k8s / vault — jamais en git.
+   *
+   * Les deux PREMIÈRES sont `optional` À DESSEIN : absentes, la brique
+   * concernée se désactive en fail-safe (2FA, webhooks) avec un log CRITIC —
+   * une application qui n'en use pas doit pouvoir démarrer sans elles. Ne pas
+   * leur ajouter `requiredIn` par symétrie : ce serait refuser de démarrer une
+   * application qui ne s'en sert pas.
+   */
+  NF_TOTP_KEY: envString({
+    optional: true,
+    description:
+      "Clé de chiffrement des secrets 2FA/TOTP au repos (32 octets base64).",
+  }),
+  NF_WEBHOOK_KEY: envString({
+    optional: true,
+    description:
+      "Clé de chiffrement des secrets de signature webhook (32 octets base64).",
+  }),
+  /**
+   * Celle-ci n'a PAS de repli acceptable. Absente, un secret est tiré au
+   * démarrage : chaque exemplaire en tire un différent, et chaque redémarrage
+   * en change — un pod refuse alors le jeton anti-CSRF qu'un autre vient
+   * d'émettre, et l'utilisateur voit un formulaire rejeté au hasard, sans la
+   * moindre erreur dans les journaux. `requiredIn` fait échouer le démarrage
+   * là où ça compte, et `nodefony doctor --env production` le dit AVANT.
+   */
+  NF_CSRF_SECRET: envString({
+    optional: true,
+    requiredIn: ["production"],
+    description:
+      "Secret des jetons anti-CSRF (synchronizer) — partagé entre process en cluster.",
+  }),
+
+  /**
+   * Mot de passe du compte admin seedé au premier boot (voir
+   * `nodefony/security/users.ts`). DEV : défaut `admin` (compte admin/admin,
+   * comme Grafana — pratique, LOCAL uniquement). PROD : OBLIGATOIRE — sans lui
+   * le seed refuse (jamais de mot de passe par défaut en production).
+   *
+   * Pas de `requiredIn` : l'exigence ne vaut qu'au PREMIER démarrage. Une fois
+   * le compte créé, la variable ne sert plus — la rendre requise ferait refuser
+   * de démarrer un déploiement qui tourne depuis des mois.
+   */
+  NF_ADMIN_PASSWORD: envString({
+    optional: true,
+    description:
+      "Mot de passe du compte admin seedé au 1er boot (obligatoire en production).",
+  }),
+<% } %><% if (it.complete || it.front) { %>
+  // L'origine publique du dev-server Vite n'est PAS une variable
+  // d'environnement : elle se dérive du `Host` de chaque requête, si bien que
+  // ton poste et un navigateur en conteneur chargent la même page en même
+  // temps, sans rien à poser. Pour un besoin durable — tunnel, proxy frontal —
+  // écris `publicOrigin` dans `nodefony.config.ts` : c'est un réglage, il gagne
+  // sur la dérivation, et il ne s'oublie pas dans un shell.
+<% } %>});

package/templates/app/base/gitattributes.tpl

@@ -0,0 +1,28 @@
+# Fins de ligne — LF PARTOUT, y compris dans la copie de travail Windows.
+#
+# Sans cette règle, git convertit les fichiers texte en CRLF au checkout Windows
+# (`core.autocrlf` y vaut `true` par défaut, et sur les runners de forge). Tout
+# ce qui compare un fichier à une sortie de générateur échoue alors sur une
+# différence invisible à l'œil : `\r\n` contre `\n`. Le message d'erreur, lui,
+# parle d'autre chose — d'un fichier « périmé », d'un test qui « ne correspond
+# pas » — et envoie chercher là où il n'y a rien.
+#
+# C'est aussi ce qui garde un diff lisible quand l'équipe mêle Windows, macOS et
+# Linux : sans cela, un fichier ouvert sous Windows ressort modifié en entier.
+* text=auto eol=lf
+
+# Binaires : jamais convertis, jamais diffés comme du texte.
+*.png binary
+*.jpg binary
+*.jpeg binary
+*.gif binary
+*.ico binary
+*.webp binary
+*.woff binary
+*.woff2 binary
+*.ttf binary
+*.otf binary
+*.pdf binary
+*.zip binary
+*.gz binary
+*.db binary