nodefony 7.0.2 → 10.0.0-alpha.2

package/templates/module/ai/AGENTS.md.tpl

@@ -0,0 +1,71 @@
+# AGENTS.md — <%= it.pkgName %>
+
+> Instructions agent de CE module. Standard AGENTS.md : **le fichier le plus
+> proche gagne** — quand tu travailles dans ce dossier, il prime sur celui de
+> l'app. Vérité COURANTE, jamais un journal : pas de dates, pas de TODO ni
+> d'historique (ça vit dans `git log`) ; un fait périmé se CORRIGE.
+
+## Rôle
+
+<%= it.description %>
+
+## Composants
+
+- `index.ts` — `<%= it.pascal %>Module extends Module`, nom kernel `<%= it.name %>`. Valide sa config à `onKernelRegister`.
+<% if (it.service) { %>- `<%= it.pascal %>Service` — `@injectable`, nom `<%= it.name %>`. Se récupère par `container.get("<%= it.name %>")`.
+<% } %><% if (it.command) { %>- `<%= it.pascal %>Command` — CLI `nodefony <%= it.name %>:hello`, `kernelEvent: onReady` (zéro serveur).
+<% } %><% if (it.controller !== "none") { %>- `<%= it.pascal %>Controller` — saveur `<%= it.controller %>`, monté sous `/api/<%= it.name %>`<% if (it.needsRealtime) { %> (socket Nodefony : canaux pub/sub + actions RPC)<% } %>. Un controller TRADUIT (HTTP/WS ↔ service), il ne décide pas.
+<% } %><% if (it.front) { %>- `frontend/` — entry Vite <%= it.frontend %> (HMR en dev, statics buildés en prod).
+<% } %>- `nodefony/config/config.ts` — schéma Zod = **source unique des défauts**. `defineModuleConfig.ts` = builder pur (valide et gèle, ne retape jamais une valeur).
+
+## Config
+
+| Clé        | Type      | Défaut                           |
+| ---------- | --------- | -------------------------------- |
+| `enabled`  | `boolean` | `true`                           |
+| `greeting` | `string`  | `"Bonjour de <%= it.name %>"` |
+
+Chargement : `use("<%= it.pkgName %>", { … })` dans le `nodefony.config.ts` de
+l'app. Config invalide → boot FATAL, champ nommé.
+
+## Décisions figées
+
+- **La logique vit dans le service**, pas dans les controllers : un controller
+  traduit du HTTP/WS, un service est réutilisable (CLI, job, autre module).
+- **Jamais `Nodefony.getKernel()` au top-level** d'un fichier chargé à l'import :
+  le module deviendrait impossible à importer — donc à tester — sans serveur.
+- Workspace npm (`modules/<%= it.name %>/`) : le Kernel charge le module PAR SON
+  NOM → il doit rester résolvable (symlink npm workspaces).
+- **Le container DI est PROTOTYPAL** : un service posé ici est visible du
+  kernel ENTIER et de chaque scope de requête (chaîne de prototypes, zéro
+  copie par requête) ; ce qu'un scope `set()` meurt avec sa requête. Ni cache
+  de services maison, ni singleton maison — `container.get("<nom>")` EST le
+  mécanisme. Réf : `node_modules/nodefony/docs/service.md`.
+- **Isomorphisme** : pour tout code NAVIGATEUR de ce module, le client temps
+  réel et les types du protocole s'importent du cœur (`nodefony`,
+  `nodefony/client`, `nodefony/react`) — jamais un client WS à la main, jamais
+  un type dupliqué front/back. Réf : `node_modules/nodefony/docs/client.md`.
+- **WS métier = socket Nodefony** : `nodefony create controller <nom>
+  --kind realtime --module <%= it.name %>` (canaux + actions RPC + policies) —
+  l'echo WS brut des exemples est une démo du pipeline, pas un modèle.
+
+## Interdits sans accord
+
+- Modifier `rolldown.config.ts` / `tsconfig.json`.
+- Ajouter une dépendance npm runtime sans en peser le coût.
+- Allouer par requête ce qui ne sert qu'à une minorité de requêtes (préférer
+  `null` + init au premier usage), ou attacher un listener sans prévoir son retrait.
+
+## Gotchas
+
+- Ne pas redéclarer `options` dans le service (la classe `Service` l'assigne via `super()`).
+- Ajouter un controller/front : `nodefony create controller|front <nom> --module <%= it.name %>` (câble l'`index.ts` seul).
+- Ajouter une commande CLI : `nodefony create command <action> --module <%= it.pkgName %>` → `nodefony <%= it.name %>:<action>` (le préfixe est ajouté seul, le `this.addCommand(…)` aussi).
+- Ajouter un service : `nodefony create service <Nom> --module <%= it.pkgName %>` (câble le `@services([…])` seul). Un service Nodefony est `@injectable()` + `extends Service` — une classe à méthodes `static` compile mais reste invisible au conteneur.
+- Build : `rolldown` → `dist/index.js` (chargé par le Kernel). En dev, le superviseur rebuild tout seul.
+
+## Gates avant commit
+
+```bash
+npm run typecheck && npm test && npm run build
+```

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

@@ -0,0 +1,62 @@
+# <%= it.pkgName %>
+
+
+<%= it.description %>
+
+
+Module applicatif Nodefony — un **workspace npm**
+(`<%= it.moduleDir %>/<%= it.name %>/`) chargé par le
+manifeste `modules` de `nodefony.config.ts` de l'app :
+
+```ts
+use("<%= it.pkgName %>", { enabled: true }),
+```
+
+## Configuration
+
+| Clé        | Type      | Défaut                           | Rôle                                        |
+| ---------- | --------- | -------------------------------- | ------------------------------------------- |
+| `enabled`  | `boolean` | `true`                           | Interrupteur du module                      |
+| `greeting` | `string`  | `"Bonjour de <%= it.name %>"` | Exemple de champ — à remplacer par la vôtre |
+
+La source unique est le schéma Zod de `nodefony/config/config.ts` : c'est lui qui porte
+les défauts, les descriptions et la validation. Une clé inconnue ou mal typée fait échouer
+le **boot**, en nommant le champ fautif.
+
+## Développer
+
+```bash
+npm run build       # rolldown → dist/ (le Kernel charge dist/index.js)
+npm run typecheck   # tsgo --noEmit
+npm test            # vitest
+```
+
+En développement, le serveur (`npm run dev` à la racine de l'app) surveille les sources et
+reconstruit tout seul : pas besoin de builder à la main à chaque changement.
+
+## Ajouter des briques
+
+Depuis la **racine de l'app** :
+
+```bash
+nodefony create controller articles --module <%= it.name %>   # HTTP + WebSocket
+nodefony create front dashboard --module <%= it.name %>       # page Vite (React/Vue/Angular)
+```
+
+Les deux commandes câblent elles-mêmes l'`index.ts` du module.
+
+## Structure
+
+```
+modules/<%= it.name %>/
+├── index.ts                    ← la classe Module (controllers, services, config)
+├── nodefony/
+│   ├── config/config.ts        ← schéma Zod = source unique des défauts
+│   ├── config/defineModuleConfig.ts ← builder pur (valide, gèle)
+<% if (it.service) { %>│   ├── service/<%= it.pascal %>Service.ts ← la logique, injectable (`container.get("<%= it.name %>")`)
+│   ├── interfaces/             ← l'API publique du service
+<% } %><% if (it.command) { %>│   ├── command/<%= it.pascal %>Command.ts ← commande CLI `nodefony <%= it.name %>:hello`
+<% } %>│   └── src/errors/             ← erreurs typées (code machine + contexte)
+├── docs/                       ← documentation, surfacée dans Studio
+└── tests/
+```

package/templates/module/base/docs/index.md.tpl

@@ -0,0 +1,55 @@
+---
+module: "<%= it.pkgName %>"
+topic: overview
+audience: [human, ai]
+tags: [module]
+status: draft
+---
+
+# <%= it.name %>
+
+
+> <%= it.description %>
+
+
+Cette page est **surfacée dans Studio** (onglet Docs du module) : ce que vous écrivez ici,
+l'équipe le lit dans l'admin, sans quitter l'application.
+
+## Ce que fait le module
+
+À remplir : le problème que ce module résout, et pour qui.
+
+## Configuration
+
+Le module se charge et se configure depuis le manifeste de l'app (`nodefony.config.ts`) :
+
+```ts
+use("<%= it.pkgName %>", {
+  enabled: true,
+  greeting: "Bonjour",
+}),
+```
+
+Les clés disponibles, leurs types et leurs défauts viennent du schéma Zod
+(`nodefony/config/config.ts`) — c'est la **source unique** : la doc, la validation au boot et
+le formulaire d'édition de Studio en dérivent tous les trois.
+<% if (it.service) { %>
+## Service
+
+`<%= it.pascal %>Service` est injectable sous le nom `<%= it.name %>` :
+
+```ts
+const svc = container.get<<%= it.pascal %>Service>("<%= it.name %>");
+svc.status(); // { ready: true }
+```
+<% } %><% if (it.command) { %>
+## Commande CLI
+
+```bash
+nodefony <%= it.name %>:hello
+```
+<% } %>
+## À suivre
+
+- Les routes exposées (une fois vos controllers écrits).
+- Les décisions d'architecture qui méritent d'être expliquées plutôt que devinées.

package/templates/module/base/index.ts.tpl

@@ -0,0 +1,50 @@
+import { Kernel, Module<% if (it.service) { %>, services<% } %> } from "nodefony";
+import { controllers } from "@nodefony/framework";
+import config, { type <%= it.pascal %>ConfigInput } from "./nodefony/config/config";
+import { define<%= it.pascal %>Config } from "./nodefony/config/defineModuleConfig";
+<% if (it.service) { %>import <%= it.pascal %>Service from "./nodefony/service/<%= it.pascal %>Service";
+<% } %>
+/**
+ * <%= it.pkgName %> — <%= it.description %>
+
+ *
+ * Module applicatif : un workspace npm à part entière
+ * (`<%= it.moduleDir %>/<%= it.name %>/`), chargé par le manifeste `modules` de
+ * `nodefony.config.ts`. Le Kernel l'importe PAR SON NOM (`<%= it.pkgName %>`) —
+ * d'où le workspace, qui le rend résolvable.
+ */
+
+/**
+ * Rend la config du module typée à l'appel : `use("<%= it.pkgName %>", { … })`
+ * dans `nodefony.config.ts` propose les clés du schéma et refuse les fautes de
+ * frappe, au lieu d'avaler un `Record<string, unknown>`.
+ */
+declare module "nodefony" {
+  interface NodefonyModuleConfig {
+    "<%= it.pkgName %>": <%= it.pascal %>ConfigInput;
+  }
+}
+
+// Les controllers du module se déclarent ici — `nodefony create controller <nom>
+// --module <%= it.name %>` les ajoute à cette liste (et à ce dossier) tout seul.
+@controllers([])
+<% if (it.service) { %>@services([<%= it.pascal %>Service])
+<% } %>class <%= it.pascal %>Module extends Module {
+  constructor(kernel: Kernel) {
+    super("<%= it.name %>", kernel, import.meta.url, config);
+  }
+
+  /**
+   * Valide la config au boot — défauts du schéma fusionnés avec ce que l'app
+   * passe dans `use()`. Une clé inconnue ou mal typée plante ICI, avec le champ
+   * fautif nommé, plutôt qu'en `undefined.x` au premier appel en production.
+   */
+  override async onKernelRegister(): Promise<this> {
+    this.options = define<%= it.pascal %>Config(
+      (this.options as <%= it.pascal %>ConfigInput) ?? {},
+    );
+    return this;
+  }
+}
+
+export default <%= it.pascal %>Module;

package/templates/module/base/nodefony/config/config.ts.tpl

@@ -0,0 +1,60 @@
+import { z } from "zod";
+
+/**
+ * <%= it.pkgName %> — CONFIGURATION DU MODULE (schéma Zod = source unique).
+ *
+ * ⭐ TL;DR : CE SCHÉMA EST LA CONFIG. Chaque `.default(...)` est la valeur d'usine ;
+ * changer un défaut du module = ÉDITER ICI (et nulle part ailleurs). L'app, elle,
+ * ne surcharge que ses écarts, via `use("<%= it.pkgName %>", { … })`.
+ *
+ * RÈGLE D'OR (ADR-0006) : ce fichier porte le schéma commenté (type + validation +
+ * défaut + doc) ET matérialise les défauts par `parse({})`. Le builder
+ * (`define<%= it.pascal %>Config`) importe le schéma d'ici et ne retape aucune valeur —
+ * un défaut écrit à deux endroits finit toujours par diverger.
+ *
+ * SURCHARGE (précédence croissante) :
+ *   • défauts du schéma (ce fichier) ;
+ *   • app : `use("<%= it.pkgName %>", { … })` dans `nodefony.config.ts` ;
+ *   • déploiement : `NF__<%= it.upper %>__<CHEMIN>=valeur` (override env générique, `__` = niveau).
+ *
+ * Le schéma reste **PUR** : aucune lecture de `process.env`, aucun accès au kernel
+ * (il est évalué à l'import — le kernel n'existe pas encore).
+ *
+ * Champ sensible (clé, mot de passe) → `.meta({ secret: true })` EN DERNIER de la
+ * chaîne : chaque méthode zod clone, une `.default()` posée après `.meta()` perdrait
+ * la métadonnée. Ces flags ressortent dans le JSON Schema lu par Studio.
+ */
+/**
+ * ⚠️ `strictObject`, et non `object` : une clé INCONNUE doit être REFUSÉE, pas
+ * retirée en silence. C'est le défaut par défaut de Zod, et il coûte cher —
+ * `use("<%= it.pkgName %>", { gretting: "…" })` produisait une application qui
+ * démarre en IGNORANT ce que l'utilisateur a écrit, sans un mot. Le typage du
+ * registre `NodefonyModuleConfig` attrape la faute de frappe à la COMPILATION ;
+ * ceci l'attrape au DÉMARRAGE, pour tout ce qui contourne le compilateur — une
+ * config chargée d'un fichier, un `as never`, un override d'environnement.
+ */
+export const <%= it.camel %>ConfigSchema = z.strictObject({
+  /** Interrupteur du module — l'app peut le charger sans l'activer. */
+  enabled: z
+    .boolean()
+    .default(true)
+    .describe("Active les fonctionnalités du module <%= it.name %>"),
+
+  /** Exemple : à remplacer par la vraie config du module. */
+  greeting: z
+    .string()
+    .min(1)
+    .default("Bonjour de <%= it.name %>")
+    .describe("Message renvoyé par le service (exemple de champ configurable)"),
+});
+
+/** Config telle que l'APP l'écrit dans `use()` — tous les champs optionnels. */
+export type <%= it.pascal %>ConfigInput = z.input<typeof <%= it.camel %>ConfigSchema>;
+
+/** Config telle que le CODE la lit — défauts appliqués, rien d'optionnel. */
+export type <%= it.pascal %>Config = z.output<typeof <%= it.camel %>ConfigSchema>;
+
+/** Défauts matérialisés (passés au `super()` du Module). */
+const defaults: <%= it.pascal %>Config = <%= it.camel %>ConfigSchema.parse({});
+
+export default defaults;

package/templates/module/base/nodefony/config/defineModuleConfig.ts.tpl

@@ -0,0 +1,55 @@
+import { z } from "zod";
+import { parseModuleConfig } from "nodefony";
+import { <%= it.camel %>ConfigSchema } from "./config";
+import type { <%= it.pascal %>Config, <%= it.pascal %>ConfigInput } from "./config";
+
+/**
+ * <%= it.pkgName %> — LE COMMENT : builder PUR de la config.
+ *
+ * ⭐ TL;DR : ce fichier VALIDE et GÈLE. Il ne porte AUCUNE valeur — les défauts
+ * vivent dans le schéma de `./config.ts` (règle d'or ADR-0006). Pour changer un
+ * défaut, c'est là-bas ; ici, on ne fait que le faire respecter.
+ *
+ * Le nom du FICHIER est le même dans tous les modules Nodefony
+ * (`defineModuleConfig.ts`) ; la FONCTION, elle, est préfixée par le module —
+ * deux modules importés côte à côte ne se marchent pas dessus.
+ *
+ * L'override env générique (`NF__<%= it.upper %>__<CHEMIN>`) est appliqué par le core,
+ * pas ici. Si le module a besoin d'une variable d'env DÉDIÉE, elle s'applique
+ * APRÈS le parse, dans cette fonction, pour que le schéma reste pur.
+ *
+ * 🔴 **La validation passe par `parseModuleConfig`, du cœur** — un seul endroit
+ * pour une seule règle. Il lève une `BootConfigurationError`, et pas une `Error`
+ * ordinaire : le kernel distingue les deux. Un hook de cycle de vie qui lève une
+ * erreur QUELCONQUE est absorbé en développement (fail-soft — il protège la DX
+ * d'un module optionnel cassé), tandis qu'une erreur de CONFIGURATION interrompt
+ * le boot dans TOUS les environnements. Mesuré sur un module généré : avec une
+ * `Error`, `use("<%= it.pkgName %>", { gretting: "…" })` laissait l'application
+ * démarrer, servir, et rendre 0 — la faute de frappe n'atteignait personne. Une
+ * configuration explicite qu'on ne peut pas honorer ne se répare pas en
+ * continuant.
+ *
+ * ⚠️ Ne PAS réécrire ce bloc à la main : les dix modules du framework portaient
+ * chacun leur copie du `try`/`catch`, et elles avaient divergé sur les deux
+ * points qui comptent — le type de l'erreur levée et la langue du message.
+ *
+ * @param config - config brute venue de `use("<%= it.pkgName %>", { … })`.
+ * @returns config validée et gelée.
+ * @throws BootConfigurationError si un champ est invalide ou inconnu (toutes les
+ *   erreurs Zod agrégées, par champ) — le boot s'interrompt, en dev comme en prod.
+ */
+export function define<%= it.pascal %>Config(
+  config: <%= it.pascal %>ConfigInput = {},
+): <%= it.pascal %>Config {
+  return Object.freeze(
+    parseModuleConfig(<%= it.camel %>ConfigSchema, config, "<%= it.pkgName %>"),
+  );
+}
+
+/**
+ * JSON Schema de la config — Studio en dérive son formulaire d'édition
+ * (libellés, types, défauts, descriptions), sans une ligne d'UI écrite à la main.
+ */
+export function <%= it.camel %>ConfigJsonSchema(): unknown {
+  return z.toJSONSchema(<%= it.camel %>ConfigSchema);
+}

package/templates/module/base/nodefony/src/errors/__PASCAL__Error.ts.tpl

@@ -0,0 +1,20 @@
+/**
+ * Erreur du module <%= it.name %>.
+ *
+ * Deux champs qui font la différence en production :
+ *  - `code` : identifiant MACHINE (stable, grep-able, consommé par Studio et
+ *    l'audit) — le message, lui, peut changer sans rien casser ;
+ *  - `context` : payload structuré joint au log (jamais de secret ici).
+ */
+export class <%= it.pascal %>Error extends Error {
+  constructor(
+    message: string,
+    public readonly code: string = "<%= it.upper %>_ERROR",
+    public readonly context?: Record<string, unknown>,
+  ) {
+    super(message);
+    this.name = "<%= it.pascal %>Error";
+  }
+}
+
+export default <%= it.pascal %>Error;

package/templates/module/base/package.json.tpl

@@ -0,0 +1,53 @@
+{
+  "name": "<%= it.pkgName %>",
+  "version": "<%= it.version %>",
+<% if (it.publishable) { %>  "type": "module",
+  "description": "<%= it.description %>",
+  "main": "./dist/index.js",
+  "types": "./dist/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/types/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "docs"
+  ],
+  "scripts": {
+    "build": "rolldown -c rolldown.config.ts && tsgo -p tsconfig.declarations.json",
+    "typecheck": "tsgo --noEmit -p tsconfig.json && tsgo --noEmit -p tsconfig.tests.json",
+    "test": "vitest run"
+  },
+<% } else { %>  "private": true,
+  "type": "module",
+  "description": "<%= it.description %>",
+  "main": "dist/index.js",
+  "scripts": {
+    "build": "rolldown -c rolldown.config.ts",
+    "typecheck": "tsgo --noEmit",
+    "test": "vitest run"
+  },
+<% } %>  "peerDependencies": {
+    "nodefony": "*",
+    "@nodefony/framework": "*",
+<% if (it.needsRealtime) { %>    "@nodefony/realtime": "*",
+<% } %><% if (it.front) { %>    "@nodefony/frontend": "*",
+<% } %><% if (it.publishable) { %>    "zod": "<%= it.pkg["zod"] %>",
+<% } %>    "@nodefony/http": "*"
+  },
+<% if (it.publishable) { %>  "devDependencies": {
+    "nodefony": "*",
+    "@nodefony/framework": "*",
+<% if (it.needsRealtime) { %>    "@nodefony/realtime": "*",
+<% } %><% if (it.front) { %>    "@nodefony/frontend": "*",
+<% } %>    "@nodefony/http": "*"
+  },
+  "dependencies": {
+    "tslib": "<%= it.pkg["tslib"] %>"
+  }
+<% } else { %>  "dependencies": {
+    "zod": "<%= it.pkg["zod"] %>"
+  }
+<% } %>}

package/templates/module/base/rolldown.config.ts.tpl

@@ -0,0 +1,14 @@
+import { defineNodefonyRolldownConfig } from "nodefony/bundler";
+
+/**
+ * Build du module — socle rolldown PARTAGÉ du framework (`nodefony/bundler`),
+ * exactement comme l'app : `preserveModules` (l'arborescence source est
+ * reproduite dans `dist/`), plateforme node, ESM.
+ *
+ * `externalDeps` externalise tout ce que le module DÉCLARE (peerDependencies +
+ * dependencies) : `nodefony`, `@nodefony/*` et `zod` ne sont pas recopiés dans
+ * le bundle — ils sont résolus au runtime depuis les node_modules de l'app.
+ * Le Kernel charge ensuite `dist/index.js` par le nom du paquet
+ * (manifeste `modules` de `nodefony.config.ts`).
+ */
+export default defineNodefonyRolldownConfig({ externalDeps: true });

package/templates/module/base/tests/__KEBAB__.test.ts.tpl

@@ -0,0 +1,39 @@
+import { describe, it, expect } from "vitest";
+import { define<%= it.pascal %>Config } from "../nodefony/config/defineModuleConfig";
+import defaults from "../nodefony/config/config";
+import <%= it.pascal %>Module from "../index";
+
+/**
+ * Ce que ce test prouve (et pourquoi il existe dès la naissance du module) :
+ *  1. le module s'IMPORTE sans kernel — donc il reste testable hors serveur
+ *     (un module qui déréférence le kernel au chargement est intestable) ;
+ *  2. sa config a des défauts sûrs et REFUSE ce qui est invalide — la panne
+ *     arrive au boot, nommée, pas en production sur un `undefined`.
+ */
+describe("<%= it.name %>", () => {
+  it("s'importe sans kernel", () => {
+    expect(<%= it.pascal %>Module).toBeTypeOf("function");
+  });
+
+  it("applique ses défauts", () => {
+    const config = define<%= it.pascal %>Config({});
+    expect(config.enabled).toBe(true);
+    expect(config.greeting).toBe(defaults.greeting);
+  });
+
+  it("refuse une config invalide", () => {
+    expect(() =>
+      define<%= it.pascal %>Config({ greeting: "" } as never),
+    ).toThrow(/greeting/u);
+  });
+
+  // Une faute de frappe n'est pas une valeur invalide : Zod retire par défaut
+  // les clés qu'il ne connaît PAS, si bien que l'application démarrerait en
+  // ignorant ce qui a été écrit. Le schéma est `strictObject` pour cette raison,
+  // et ce cas est ce qui l'empêche de redevenir un `object` au premier refactor.
+  it("refuse une clé INCONNUE plutôt que de l'ignorer", () => {
+    expect(() =>
+      define<%= it.pascal %>Config({ gretting: "faute de frappe" } as never),
+    ).toThrow(/gretting/u);
+  });
+});

package/templates/module/base/tsconfig.json.tpl

@@ -0,0 +1,42 @@
+{
+  "compilerOptions": {
+    "target": "ES2024",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "lib": ["ESNext", "DOM", "DOM.Iterable"],
+    "types": ["node"],
+    "rootDir": "./",
+    "outDir": "./dist",
+    "strict": true,
+    "experimentalDecorators": true,
+    "emitDecoratorMetadata": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "resolveJsonModule": true,
+    "forceConsistentCasingInFileNames": true,
+<% if (it.frontend === "react") { %>    "jsx": "react-jsx",
+<% } %><% if (it.publishable) { %>    "stripInternal": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "declaration": true,
+    "declarationDir": "./dist/types"
+<% } else { %>    "noEmit": true
+<% } %>  },
+  "include": [
+    "index.ts",
+    "rolldown.config.ts",
+<% if (!it.publishable) { %>    "vitest.config.ts",
+<% } %>    "nodefony/**/*.ts"<% if (it.frontend === "react") { %>,
+    "frontend/src/**/*"<% } %><% if (it.frontend === "vue" || it.frontend === "angular" || it.frontend === "svelte") { %>,
+    "frontend/src/**/*.ts"<% } %><% if (!it.publishable) { %>,
+    "tests/**/*.ts"<% } %>
+  ],
+<% if (it.publishable) { %>  "exclude": [
+    "node_modules",
+    "dist",
+    "tests/**",
+    "**/*.test.ts",
+    "vitest.config.ts"
+  ]
+<% } else { %>  "exclude": ["node_modules", "dist"]
+<% } %>}

package/templates/module/base/vitest.config.ts.tpl

@@ -0,0 +1,27 @@
+import { defineConfig } from "vitest/config";
+
+/**
+ * Config Vitest du module — suite UNITAIRE, qui ne frappe jamais le réseau.
+ *
+ * ⚠️ Le bloc `oxc` est OBLIGATOIRE : Vitest transforme les tests via oxc/rolldown,
+ * qui ne lit PAS le `experimentalDecorators` du tsconfig. Sans lui, les décorateurs
+ * (@controller, @route, @services, DI) sortiraient bruts et Node lèverait
+ * `SyntaxError` au chargement. `emitDecoratorMetadata` est requis par l'injection
+ * de dépendances (résolution des types constructeur via `design:paramtypes`).
+ *
+ * ⚠️ Les `*.e2e.test.ts` sont EXCLUS, exactement comme dans l'application.
+ * `nodefony create entity --module <ce module>` en pose un par ressource, et un
+ * test de bout en bout suppose un serveur DÉMARRÉ : c'est la suite e2e de
+ * l'application qui le lance, une fois pour toutes, puisqu'un module ne démarre
+ * pas seul. Sans cette exclusion, `npm test` du module frappe un serveur absent
+ * et échoue — chaque gabarit étant pourtant juste isolément.
+ */
+export default defineConfig({
+  test: {
+    include: ["tests/**/*.test.ts"],
+    exclude: ["**/node_modules/**", "**/dist/**", "tests/**/*.e2e.test.ts"],
+  },
+  oxc: {
+    decorator: { legacy: true, emitDecoratorMetadata: true },
+  },
+});

package/templates/module/packages/CLAUDE.md.tpl

@@ -0,0 +1,51 @@
+# CLAUDE.md — <%= it.pkgName %>
+
+
+> Fiche d'INSTRUCTIONS pour une IA qui va coder dans ce paquet. À lire AVANT
+> d'éditer. Compléments : [`MEMORY.md`](./MEMORY.md) (internals, gotchas),
+> [`README.md`](./README.md) (usage humain), [`AGENTS.md`](./AGENTS.md)
+> (contexte agent, standard « le plus proche gagne »).
+
+## Rôle du module
+
+<%= it.description %>
+
+
+## Structure
+
+```
+<%= it.name %>/
+├── index.ts                                   ← classe Module + @services + re-exports publics
+├── nodefony/
+│   ├── config/{config.ts,defineModuleConfig.ts}  ← schéma Zod (source unique) + builder
+│   ├── service/<%= it.pascal %>Service.ts        ← service injectable
+│   ├── interfaces/I<%= it.pascal %>Service.ts    ← contrat public
+│   └── src/errors/<%= it.pascal %>Error.ts       ← erreurs typées
+├── tests/                                      ← vitest
+└── docs/                                       ← doc du module (surfacée dans Studio)
+```
+
+## Décisions figées
+
+- **Paquet PUBLIABLE** : `exports`/`types` pointent vers du GÉNÉRÉ (`dist/`,
+  `dist/types/`) — jamais un `.d.ts` écrit à la main. `files` borne ce qui part
+  sur npm.
+- **Config Zod** : `config/config.ts` est la SOURCE UNIQUE (type + validation +
+  défaut + doc). Un défaut ne se retape nulle part ailleurs. Validée au boot
+  (`onKernelRegister`) → plante propre, jamais un `undefined.x` silencieux.
+- **TypeScript strict** — zéro `any`, zéro `@ts-ignore`, ESM seul, imports Node
+  préfixés `node:`, interfaces préfixées `I`.
+
+## Ce qu'il ne faut JAMAIS faire sans accord
+
+- Modifier `rolldown.config.ts` / `tsconfig*.json`.
+- Retaper un défaut de config ailleurs que dans le schéma Zod.
+- Ajouter une dépendance runtime sans peser son coût (taille + mémoire).
+
+## Tests / build
+
+```bash
+npm test        # vitest run
+npm run build   # rolldown + déclarations .d.ts
+npm run typecheck
+```

package/templates/module/packages/MEMORY.md.tpl

@@ -0,0 +1,39 @@
+# MEMORY.md — <%= it.pkgName %>
+
+
+> Internals pour une IA en cours de session. Ultra-concis, zéro prose, zéro
+> date : ce fichier décrit la vérité COURANTE du code — l'historique est dans
+> `git log`. Mettre à jour = éditer la section concernée EN PLACE.
+
+## Purpose
+
+<%= it.description %>
+
+
+## Core Components
+
+| Symbole | Fichier | Rôle |
+| --- | --- | --- |
+| `<%= it.pascal %>` | `index.ts` | classe Module — déclare `@services`, valide la config |
+| `<%= it.pascal %>Service` | `nodefony/service/<%= it.pascal %>Service.ts` | service injectable, clé conteneur `<%= it.name %>` |
+| `<%= it.camel %>ConfigSchema` | `nodefony/config/config.ts` | schéma Zod = source unique des défauts |
+| `define<%= it.pascal %>Config` | `nodefony/config/defineModuleConfig.ts` | parse + freeze au boot |
+| `<%= it.pascal %>Error` | `nodefony/src/errors/<%= it.pascal %>Error.ts` | erreurs typées du module |
+
+## Config
+
+- Surcharge par l'app : `use("<%= it.pkgName %>", { … })` dans son `nodefony.config.ts`.
+- Surcharge par l'environnement : `NF__<%= it.upper %>__<CHEMIN>`.
+- Défauts matérialisés par `<%= it.camel %>ConfigSchema.parse({})` — ne jamais les retaper.
+
+## Behaviors
+
+- `onKernelRegister` valide la config et réassigne `this.options` AVANT que les
+  `@services` ne soient instanciés (`onBoot`).
+
+## Gotchas
+
+- La clé de CONTENEUR (`super("<%= it.name %>", …)`) n'est pas le nom de la CLASSE :
+  `container.get("<%= it.name %>")`.
+- Ne jamais déréférencer le Kernel au top-level d'un fichier chargé à l'import
+  (`Nodefony.getKernel()` rend `null` avant le boot) — passer par un getter.