nodefony 7.0.2 → 10.0.0-alpha.2

package/templates/app/complete/env.tpl

@@ -0,0 +1,53 @@
+# ══════════════════════════════════════════════════════════════════════════
+#  Environnement de <%= it.appName %> — fichier COMMITÉ (défauts NON-secrets)
+# ══════════════════════════════════════════════════════════════════════════
+# Convention (celle du framework, style Vite/Next) :
+#   .env        → CE fichier : catalogue + défauts partagés, JAMAIS de secret
+#   .env.local  → tes valeurs machine + SECRETS (gitignoré via *.local,
+#                 généré à la création de l'app)
+# Priorité de chargement : .env.local PRIME sur .env (première clé gagne).
+# Chaque variable est déclarée et validée dans env.ts (seul lecteur de
+# process.env) — une variable non déclarée là-bas n'existe pas pour l'app.
+
+# ── Réseau ──────────────────────────────────────────────────────────────────
+# Ports d'écoute. Absents = défauts du framework (HTTP 5151, HTTPS 5152).
+# En DEV, si le port est déjà pris (une autre app Nodefony), l'app prend le
+# suivant libre et l'ANNONCE (`portPolicy: "auto"`). En PRODUCTION le port est un
+# CONTRAT (service, ingress, sonde) : occupé = échec franc (`portPolicy: "strict"`).
+# `PORT` est l'alias des plateformes (Cloud Run, Heroku, Railway) — elles
+# l'injectent elles-mêmes ; `NF_PORT` l'emporte si les deux sont là.
+# NF_PORT=5151
+# NF_PORT_HTTPS=5152
+
+# ── Observabilité ───────────────────────────────────────────────────────────
+# Sink des logs : stdout (cloud-native, défaut) | file | null
+# NF_LOG_DRIVER=stdout
+
+# ── Persistance (infra déclarée → stores dérivés automatiquement) ───────────
+# URL unique, dialecte déduit du scheme. ABSENTE = profil solo : sqlite local
+# (var/databases/) — l'app persiste out-of-the-box (users, sessions, jetons).
+<% if (it.db) { %># Tu as retenu <%= it.db.label %> à la création : l'URL ci-dessous joint le service
+# du `compose.yaml` généré. Lance-le avant l'app — `npm run infra:up`.
+# (Repasser en sqlite local : commente cette ligne, rien d'autre à changer.)
+# Elle joint le service `<%= it.db.service %>` du compose, avec ses identifiants de dev.
+NF_DATABASE_URL=<%= it.db.url %>
+
+<% } else { %># NF_DATABASE_URL=postgres://user:pass@localhost:5432/<%= it.appName %> (exemple)
+
+<% } %>
+
+# Cache/éphémère partagé : sa présence CHARGE @nodefony/redis (sessions,
+# idempotence, backplane realtime cross-pod).
+# NF_REDIS_URL=redis://localhost:6379
+
+# ── Secrets (module security) — VALEURS dans .env.local, jamais ici ─────────
+# Générées à la création de l'app ; rotation/rattrapage :
+#   npx nodefony security:secrets --write
+# NF_TOTP_KEY=        → .env.local (chiffrement des secrets 2FA au repos)
+# NF_WEBHOOK_KEY=     → .env.local (chiffrement des signatures webhook)
+# NF_CSRF_SECRET=     → .env.local (jetons anti-CSRF, partagé en cluster)
+
+# ── Compte admin (seedé au premier boot — nodefony/security/provisionUsers.ts)
+# DEV : défaut admin / admin (local). PROD : OBLIGATOIRE, sans lui aucun compte
+# n'est créé (le définir via le secret-manager, pas dans un fichier commité).
+# NF_ADMIN_PASSWORD=

package/templates/app/complete/nodefony/entity/User.ts.tpl

@@ -0,0 +1,69 @@
+import { defineEntity } from "@nodefony/orm-core";
+import { createUserTable, FRAMEWORK_CONNECTOR } from "@nodefony/drizzle";
+import type { SqlDialect } from "@nodefony/drizzle";
+
+/**
+ * L'entité `User` de cette application.
+ *
+ * **L'identité appartient à ton application**, pas au framework : c'est toi qui
+ * décris cette table, qui y ajoutes tes champs et qui en portes les migrations.
+ * Sans ce fichier, l'application marcherait en développement — où le schéma est
+ * dérivé du code — et refuserait de servir en production, où personne ne créerait
+ * la table.
+ *
+ * ## Ajouter tes propres champs
+ *
+ * Ne modifie pas ce fichier à la main : relance la commande avec tes champs, elle
+ * réécrit l'entité avec les colonnes du contrat EN CLAIR, plus les tiennes.
+ *
+ * ```bash
+ * nodefony create entity User firstName:string(100)? department:string?
+ * ```
+ *
+ * Un champ obligatoire doit avoir une valeur par défaut (`role:string=membre`) ou
+ * être facultatif (`department:string?`) : le framework crée des utilisateurs sans
+ * le connaître — au semis d'un administrateur, à la première connexion par un
+ * fournisseur externe — et ces créations échoueraient.
+ *
+ * ## Écrire et lire un champ métier
+ *
+ * En ÉCRITURE, `IUserRepository` est typé sur le contrat et refuse tes champs :
+ * la porte est le dépôt générique, `orm.getRepository("User")`. En LECTURE il n'y
+ * a rien à faire — le dépôt reporte toute colonne hors contrat sur l'utilisateur.
+ *
+ * ## Après un changement de schéma
+ *
+ * ```bash
+ * nodefony orm:generate --name utilisateur   # écrit la migration
+ * nodefony orm:migrate                       # l'applique
+ * ```
+ */
+/**
+ * Le moteur choisi à la création de cette application.
+ *
+ * Il est FIGÉ ici, comme dans toute entité générée : une table Drizzle est
+ * écrite pour un dialecte: `sqliteTable` et `pgTable` n'ont ni les mêmes types
+ * ni les mêmes options. Changer de moteur demande donc de changer cette ligne —
+ * et d'écrire la migration correspondante, ce que `orm:generate` fait pour toi.
+ *
+ * (Il n'est PAS déduit de l'environnement : dans une application Nodefony,
+ * `env.ts` en est le SEUL lecteur. Une seconde lecture ailleurs fait diverger la
+ * configuration effective de ce que le catalogue déclare.)
+ */
+const DIALECTE: SqlDialect = "<%= it.dialect %>";
+
+/**
+ * La table, EXPORTÉE — et pas seulement passée au descripteur.
+ *
+ * L'outil qui écrit les migrations est un process séparé : il lit les fichiers de
+ * `nodefony/entity/` et y cherche les tables exportées. Une table seulement
+ * passée en argument y serait invisible, et la migration s'écrirait SANS elle.
+ */
+export const userTable = createUserTable(DIALECTE);
+
+export const UserEntity = defineEntity({
+  name: "User",
+  module: "app",
+  connector: FRAMEWORK_CONNECTOR,
+  schema: userTable,
+});

package/templates/app/complete/nodefony/security/provisionUsers.ts.tpl

@@ -0,0 +1,124 @@
+import type { Module } from "nodefony";
+import { ormRegistry } from "@nodefony/orm-core";
+import { InMemoryUserRepository, UserService } from "@nodefony/user";
+import type { IPasswordEncoder } from "@nodefony/user";
+import { DrizzleUserRepository } from "@nodefony/drizzle";
+import type { DrizzleOrm } from "@nodefony/drizzle";
+import { env } from "../../env";
+
+const LOG_CTX = "USERS";
+
+/** Identifiant (login) du compte administrateur seedé au premier boot. */
+export const ADMIN_IDENTIFIER = "admin";
+
+/**
+ * Rôles du compte admin — donnés À PLAT (en plus de la hiérarchie déclarée dans
+ * `nodefony.config.ts`) : `ROLE_NODEFONY_ADMIN` ouvre la console Studio
+ * (`/nodefony`), `ROLE_ADMIN` la gestion applicative des utilisateurs.
+ */
+export const ADMIN_ROLES = ["ROLE_ADMIN", "ROLE_NODEFONY_ADMIN"];
+
+/**
+ * Pose le service applicatif `"users"` (la source d'identité du firewall) au
+ * démarrage de l'app, puis seed le compte admin s'il n'existe pas.
+ *
+ * **C'est la responsabilité de TON application, pas du framework** :
+ * `@nodefony/security` sait *authentifier*, mais c'est l'app qui décide *qui*
+ * sont ses utilisateurs et *où* ils sont stockés. Sans ce service, toutes les
+ * méthodes d'auth (mot de passe, JWT, social) échouent avec
+ * « aucun service users ».
+ *
+ * Dépôt : Drizzle (SQL — sqlite local par défaut, `NF_DATABASE_URL` pour une
+ * vraie base). Si l'ORM n'est pas chargé (module retiré du manifeste), repli
+ * ANNONCÉ sur un annuaire mémoire volatil — l'auth marche, mais les comptes ne
+ * survivent pas au redémarrage.
+ *
+ * Mot de passe admin :
+ * - DÉVELOPPEMENT : `admin` / `admin` par défaut (local uniquement — même
+ *   esprit que Grafana). Surcharge : `NF_ADMIN_PASSWORD` dans `.env.local`.
+ * - PRODUCTION : `NF_ADMIN_PASSWORD` OBLIGATOIRE (secret-manager) — sans lui,
+ *   AUCUN compte n'est créé (jamais de mot de passe par défaut en prod) et un
+ *   WARNING explique quoi faire (`nodefony security:user:add`).
+ *
+ * Idempotent et non destructif : ne remplace jamais un annuaire déjà posé, ne
+ * recrée jamais un compte existant.
+ *
+ * @param module - le module applicatif (`App`) — fournit container, kernel, log.
+ */
+export async function provisionUsers(module: Module): Promise<void> {
+  const container = module.container;
+  if (!container || container.has("users")) {
+    return;
+  }
+
+  // L'encodeur (Argon2id par défaut) est posé par le firewall (@nodefony/security).
+  // Son absence = module security non chargé → échec franc, pas de fallback muet.
+  const encoder = container.get<IPasswordEncoder>("passwordEncoder");
+  if (!encoder) {
+    throw new Error(
+      `provisionUsers: service "passwordEncoder" absent — le module ` +
+        `@nodefony/security est-il chargé dans nodefony.config.ts ?`,
+    );
+  }
+
+  // `get()` LÈVE sur un nom inconnu : interroger AVANT, sinon ce repli
+  // fail-soft — tout l'objet du bloc qui suit — ne s'exécute jamais et le
+  // boot casse là où il devait dégrader.
+  const orm = ormRegistry.has("default")
+    ? (ormRegistry.get("default") as DrizzleOrm)
+    : undefined;
+  if (!orm) {
+    // Repli ANNONCÉ (jamais silencieux) : sans ORM, annuaire mémoire volatil.
+    module.log(
+      `ORM "default" absent (module @nodefony/drizzle retiré ?) → annuaire ` +
+        `utilisateurs EN MÉMOIRE : les comptes ne survivront pas au redémarrage.`,
+      "WARNING",
+      LOG_CTX,
+    );
+    const users = new UserService(new InMemoryUserRepository([]), encoder);
+    container.set("users", users);
+    await seedAdmin(users, module);
+    return;
+  }
+
+  const users = new UserService(DrizzleUserRepository.from(orm), encoder);
+  container.set("users", users);
+  await seedAdmin(users, module);
+}
+
+/**
+ * Crée le compte admin s'il n'existe pas (idempotent). Le hash Argon2id est
+ * fait par `UserService.createUser` — jamais de mot de passe en clair stocké.
+ *
+ * @param users - service utilisateur branché sur son dépôt.
+ * @param module - module applicatif (logs + environnement).
+ */
+async function seedAdmin(users: UserService, module: Module): Promise<void> {
+  if (await users.findByIdentifier(ADMIN_IDENTIFIER)) {
+    return;
+  }
+  const isProd = module.kernel?.environment === "production";
+  const password = env.NF_ADMIN_PASSWORD ?? (isProd ? null : "admin");
+  if (!password) {
+    module.log(
+      `Aucun admin et NF_ADMIN_PASSWORD non défini → aucun compte seedé en ` +
+        `production. Définis NF_ADMIN_PASSWORD (secret-manager) ou crée un ` +
+        `compte : \`npx nodefony security:user:add admin --admin\`.`,
+      "WARNING",
+      LOG_CTX,
+    );
+    return;
+  }
+  await users.createUser({
+    identifier: ADMIN_IDENTIFIER,
+    plainPassword: password,
+    roles: ADMIN_ROLES,
+  });
+  module.log(
+    isProd
+      ? `Compte admin seedé (mot de passe : NF_ADMIN_PASSWORD).`
+      : `Compte admin seedé — connexion : admin / ${env.NF_ADMIN_PASSWORD ? "(NF_ADMIN_PASSWORD)" : "admin"} (Studio : /nodefony).`,
+    "INFO",
+    LOG_CTX,
+  );
+}

package/templates/app/complete/nodefony/service/AppBannerService.ts.tpl

@@ -0,0 +1,98 @@
+import {
+  Service,
+  Module,
+  Container,
+  Event,
+  injectable,
+  inject,
+} from "nodefony";
+
+import AppInfoService from "./AppInfoService";
+
+/**
+ * ⚡ **Tu veux un service ? Ne recopie pas ce fichier — génère-le :**
+ *
+ * ```bash
+ * npx nodefony create service <Nom>                  # la classe + sa déclaration
+ * npx nodefony create service <Nom> --inject <Autre> # + la dépendance écrite
+ * ```
+ *
+ * Le générateur écrit la version COURANTE du framework et déclare le service sur
+ * le module ; recopié à la main, il naît déjà décalé et personne ne le signale.
+ * Ce fichier reste là pour se LIRE — comprendre ce qu'est un service — pas pour
+ * se dupliquer.
+ *
+ *
+ * Un service qui en CONSOMME un autre — l'exemplaire à imiter dès que ta
+ * logique a besoin d'une brique déjà écrite.
+ *
+ * `AppInfoService`, à côté, montre à quoi ressemble un service. Il ne montrait
+ * pas le geste le plus fréquent, et de loin : **s'en servir depuis ailleurs**.
+ * Sans un exemplaire sous les yeux, ce geste se réinvente — et il se réinvente
+ * mal. Les deux erreurs qui reviennent, toutes deux compilables :
+ *
+ *   `new AppInfoService(module)`      un SECOND exemplaire, qui n'est pas celui
+ *                                     du conteneur : sa configuration, son
+ *                                     `init()` et son état ne sont pas les siens
+ *   un import direct, appelé en statique
+ *                                     plus de conteneur du tout, donc plus rien
+ *                                     à remplacer en test
+ *
+ * La bonne voie est ci-dessous, et il y en a deux :
+ *
+ * 1. **Par le CONSTRUCTEUR** (`@inject`) — la dépendance est DÉCLARÉE, donc le
+ *    conteneur construit `AppInfoService` AVANT celui-ci et passe l'exemplaire
+ *    unique. C'est la voie par défaut. `@inject` prend le nom de la **CLASSE**
+ *    (`AppInfoService`), jamais la clé d'instance.
+ * 2. **Par le CONTENEUR** (`this.container.get("appInfo")`) — utile quand la
+ *    dépendance est tardive ou optionnelle. Ici c'est la clé d'**INSTANCE**,
+ *    celle que l'autre fichier passe en premier argument à son constructeur
+ *    parent — pas le nom de sa classe.
+ *
+ * Tu en veux un nouveau ? Ne recopie pas ce fichier :
+ * `npx nodefony create service <Nom> --inject AppInfoService` écrit ce
+ * constructeur pour toi, à la version courante du framework.
+ */
+@injectable()
+class AppBannerService extends Service {
+  module: Module;
+
+  constructor(
+    module: Module,
+    // La dépendance passe par le CONSTRUCTEUR : le conteneur la construit avant
+    // celui-ci et l'ordonnance. `@inject` prend le nom de la CLASSE — la clé
+    // d'instance (`"appInfo"`) ne sert qu'à `container.get`.
+    @inject("AppInfoService") private readonly appInfo: AppInfoService,
+  ) {
+    super(
+      "appBanner",
+      module.container as Container,
+      module.notificationsCenter as Event,
+    );
+    this.module = module;
+  }
+
+  /**
+   * Hook de démarrage, appelé UNE fois par le kernel après la construction.
+   *
+   * ⚠️ `init`, pas `initialize` — le kernel ne cherche que `init`.
+   */
+  async init(): Promise<this> {
+    this.log("service appBanner initialisé", "DEBUG");
+    return this;
+  }
+
+  /**
+   * Compose une ligne lisible à partir du service injecté — remplace ce corps
+   * par ta logique.
+   *
+   * Noter qu'on n'a rien reconstruit : `this.appInfo` EST l'exemplaire du
+   * conteneur, avec sa configuration et son `init()` déjà passés.
+   */
+  banner(): string {
+    const { app, env } = this.appInfo.identity();
+    return `${app} — ${env}`;
+  }
+}
+
+export default AppBannerService;

package/templates/app/complete/nodefony/service/AppInfoService.ts.tpl

@@ -0,0 +1,85 @@
+import { Service, Module, Container, Event, injectable } from "nodefony";
+
+/**
+ * ⚡ **Tu veux un service ? Ne recopie pas ce fichier — génère-le :**
+ *
+ * ```bash
+ * npx nodefony create service <Nom>                  # la classe + sa déclaration
+ * npx nodefony create service <Nom> --inject <Autre> # + la dépendance écrite
+ * ```
+ *
+ * Le générateur écrit la version COURANTE du framework et déclare le service sur
+ * le module ; recopié à la main, il naît déjà décalé et personne ne le signale.
+ * Ce fichier reste là pour se LIRE — comprendre ce qu'est un service — pas pour
+ * se dupliquer.
+ *
+ * Un SERVICE de ton application — l'exemplaire à LIRE quand tu écris de la
+ * logique métier.
+ *
+ * Il est là pour une raison précise : ton application naît avec des controllers
+ * d'exemple, et un agent — comme un développeur — imite ce qu'il a sous les
+ * yeux. Sans un service à copier, la logique finit dans un controller, ou dans
+ * une classe ordinaire instanciée à la main. Les deux COMPILENT et passent les
+ * tests ; les deux perdent tout ce que le conteneur apporte.
+ *
+ * **Quand écrire un service plutôt qu'une méthode de controller ?** Dès que le
+ * même traitement sert à DEUX endroits — deux routes, une route et une commande
+ * CLI, un controller et un canal temps réel. Un controller traduit du HTTP ou du
+ * WebSocket ; un service porte le métier, et le même exemplaire sert tous les
+ * transports sans être réécrit pour chacun.
+ *
+ * Trois choses en font un service Nodefony, et aucune n'est décorative :
+ *
+ *   `@injectable()`          le conteneur peut le construire et l'injecter
+ *   `extends Service`        il reçoit `this.log`, les événements, le conteneur
+ *   `super("appInfo", …)`    sa clé d'instance — `container.get("appInfo")`
+ *
+ * Le décorateur nomme la CLASSE (ce qu'on écrit dans `@inject("AppInfoService")`),
+ * le `super()` nomme l'INSTANCE. Les deux mènent au même exemplaire.
+ *
+ * ⚠️ Écrire cette classe ne suffit PAS : un service doit être DÉCLARÉ sur le
+ * module, dans `@services([…])` de l'`index.ts`. Une classe `@injectable()` que
+ * personne ne déclare n'existe pour personne — `npx nodefony doctor` le dit
+ * (règle `orphan-service`), mais seulement si le décorateur est là.
+ */
+@injectable()
+class AppInfoService extends Service {
+  module: Module;
+
+  constructor(module: Module) {
+    super(
+      "appInfo",
+      module.container as Container,
+      module.notificationsCenter as Event,
+    );
+    this.module = module;
+  }
+
+  /**
+   * Hook de démarrage, appelé UNE fois par le kernel après la construction.
+   *
+   * ⚠️ Il s'appelle `init`, pas `initialize` : le kernel ne cherche que `init`.
+   * Une méthode `initialize` sur un service n'est jamais appelée, et rien ne le
+   * signale. (`initialize` existe, mais sur un CONTROLLER, où il tourne à CHAQUE
+   * requête — deux cycles de vie, deux noms.)
+   */
+  async init(): Promise<this> {
+    this.log("service appInfo initialisé", "DEBUG");
+    return this;
+  }
+
+  /**
+   * La carte d'identité de l'application — remplace ce corps par ta logique.
+   *
+   * Elle lit la CONFIGURATION plutôt qu'une valeur écrite en dur : c'est ce qui
+   * permet de changer le comportement par environnement sans retoucher au code.
+   */
+  identity(): { app: string; env: string } {
+    return {
+      app: "<%= it.appName %>",
+      env: String(this.kernel?.environment ?? "development"),
+    };
+  }
+}
+
+export default AppInfoService;

package/templates/app/frontend/angular/frontend/src/accent.css.tpl

@@ -0,0 +1,34 @@
+/*
+ * Accent Angular — sa couleur et l'animation de son logo.
+ *
+ * La mise en page et la palette de la démonstration vivent dans
+ * `showcase.css`, PARTAGÉE par les trois vitrines : seules ces variables
+ * changent d'un framework à l'autre.
+ *
+ * Pourquoi un fichier CSS et non le bloc de styles du composant : Angular
+ * renomme les `@keyframes` déclarés dans `styles: [...]` (encapsulation de
+ * vue) — l'animation nommée par la variable ne serait alors plus trouvée.
+ * Les trois vitrines utilisent donc le même mécanisme, un import CSS que
+ * Vite injecte globalement.
+ */
+
+:root {
+  --nf-accent: #dd0031;
+  /* Encre : la MÊME teinte, assez foncée pour être lue SUR le lavis.
+     La couleur de marque ne se négocie pas ; sa luminosité, si — écrire
+     `--nf-accent` sur `--nf-accent-wash` donnait 2,78:1, sous le seuil AA. */
+  --nf-accent-ink: #a30024;
+  --nf-accent-glow: rgba(221, 0, 49, 0.28);
+  --nf-accent-wash: rgba(221, 0, 49, 0.1);
+  --nf-accent-line: rgba(221, 0, 49, 0.3);
+  --nf-logo-anim: nf-pulse 4s ease-in-out infinite;
+}
+@keyframes nf-pulse {
+  0%,
+  100% {
+    transform: scale(1);
+  }
+  50% {
+    transform: scale(1.07);
+  }
+}