nodefony 7.0.2 → 10.0.0-alpha.2

package/dist/node/cli/scaffold/engine.js

@@ -0,0 +1,2156 @@
+import { findReservedEntity } from "./reservedEntities.js";
+import { findProjectRoot } from "../projectRoot.js";
+import { envFileOrder } from "../../runtime/loadEnv.js";
+import { pointeursInstructions } from "../agentTargets.js";
+import { resolveInfra } from "../../config/infra.js";
+import { resolveModuleLayout } from "./moduleLayout.js";
+import { COLUMN_CASES, ENTITY_DIALECTS, ENTITY_ID_KINDS, buildEntityCodegen, describeColumnTypes, parseEntityFields, parseEntityIndexes, toSnakeCase } from "./entityFields.js";
+import { assertUserFieldsAreFillable, readUserContract, userContractFields, userTableName } from "./userContractSource.js";
+import { SCAFFOLD_VERSIONS, pick } from "./versions.js";
+import { formatScaffoldOutput } from "./format.js";
+import { ScaffoldWriter } from "./writer.js";
+import { CONTROLLER_KIND_CHOICES, getScaffoldSpec } from "./spec.js";
+import { randomBytes } from "node:crypto";
+import { existsSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { Eta } from "eta";
+//#region src/cli/scaffold/engine.ts
+/**
+* Options du moteur de gabarits, **écrites une seule fois** : sept rendus les
+* instanciaient à l'identique, et une divergence entre deux d'entre eux serait
+* passée inaperçue jusqu'au fichier produit.
+*
+* - `autoEscape: false` — on génère du CODE, pas du HTML : échapper les entités
+*   corromprait chaque fichier.
+* - `useWith: false` + `varName: "it"` — accès strict par `it.`, aucune variable
+*   implicite.
+* - `autoTrim: false` — **le défaut d'eta AVALE la ligne vide qui suit une
+*   balise en fin de ligne.** Un `# <%= it.appName %>` suivi d'une ligne vide et
+*   d'un paragraphe rendait le titre COLLÉ au paragraphe ; et en markdown, un
+*   paragraphe qui suit une liste sans ligne vide devient une continuation de la
+*   dernière puce. Le rendu n'était donc pas seulement mal formaté, il était mal
+*   STRUCTURÉ — et le formateur que l'application embarque le refusait. Ce que
+*   le gabarit écrit est ce qui sort.
+*/
+const ETA_OPTIONS = {
+	useWith: false,
+	varName: "it",
+	autoEscape: false,
+	autoTrim: false
+};
+/** Fichiers dont le nom rendu diffère du template (npm strip les dotfiles publiés). */
+const RENAMES = {
+	gitignore: ".gitignore",
+	dockerignore: ".dockerignore",
+	prettierignore: ".prettierignore",
+	gitattributes: ".gitattributes",
+	"oxlintrc.json": ".oxlintrc.json",
+	"prettierrc.json": ".prettierrc.json",
+	"gitlab-ci.yml": ".gitlab-ci.yml",
+	env: ".env",
+	"env.local": ".env.local"
+};
+/**
+* Répertoires renommés au rendu — même raison que `RENAMES` (npm strip aussi
+* les DOSSIERS pointés publiés : un `templates/…/.github/` n'arriverait jamais
+* chez l'installeur). Seul le PREMIER segment du chemin relatif est mappé.
+*/
+const DIR_RENAMES = { github: ".github" };
+/**
+* Paramètres frontend par framework — type registerEntry, entry, nœud de
+* montage, ET les dépendances npm (SOURCE UNIQUE : consommée par le
+* `package.json.tpl` de `create app` ET par `create front` qui les ajoute au
+* package.json d'une cible existante — une version ne vit qu'ici).
+*
+* ⚠️ **Le framework front lui-même est une devDependency, et `deps` est vide.**
+* Le test qui tranche est le même que pour la toolchain : *le paquet est-il
+* importé au RUNTIME du serveur ?* Ici non — aucun fichier hors `frontend/`
+* n'importe `react`/`vue`/`@angular/*` : Vite les inline dans le bundle
+* navigateur, et c'est ce bundle que la production sert. Les déclarer en
+* `dependencies` les faisait survivre au `npm prune --omit=dev` de l'image et
+* embarquer un framework entier que rien ne charge (mesuré ailleurs : 26,6 Mo
+* pour `vue` seul, y compris dans une app React).
+*
+* L'ordre du `Dockerfile` généré est ce qui rend la bascule sûre :
+* `RUN npm run build && npm prune --omit=dev` — le build les a quand il en a
+* besoin, le prune les retire ensuite. Toute recette qui élaguerait AVANT de
+* construire casserait, et c'est vrai de n'importe quelle devDependency.
+*
+* `deps` reste dans le contrat : le jour où un rendu côté serveur importera
+* vraiment le framework, c'est là que la déclaration devra revenir.
+*/
+const FRONTEND_PARAMS = {
+	react: {
+		type: "react19",
+		entry: "./frontend/src/main.tsx",
+		mountNode: "<div id=\"root\"></div>",
+		deps: {},
+		devDeps: pick("react", "react-dom", "vite", "@vitejs/plugin-react", "@types/react", "@types/react-dom")
+	},
+	vue: {
+		type: "vue3",
+		entry: "./frontend/src/main.ts",
+		mountNode: "<div id=\"app\"></div>",
+		deps: {},
+		devDeps: pick("vue", "vite", "@vitejs/plugin-vue")
+	},
+	angular: {
+		type: "angular",
+		entry: "./frontend/src/main.ts",
+		mountNode: "<app-root></app-root>",
+		deps: {},
+		devDeps: pick("@angular/core", "@angular/common", "@angular/platform-browser", "vite", "@analogjs/vite-plugin-angular", "@angular/build", "@angular/compiler-cli")
+	},
+	svelte: {
+		type: "svelte5",
+		entry: "./frontend/src/main.ts",
+		mountNode: "<div id=\"app\"></div>",
+		deps: {},
+		devDeps: pick("svelte", "vite", "@sveltejs/vite-plugin-svelte")
+	}
+};
+/**
+* Paramètres de la base SQL retenue au scaffold — SOURCE UNIQUE du service
+* docker, du port publié et de l'URL de connexion, consommée par les TROIS
+* gabarits qui en parlent (`compose.yaml`, `.env`, `README.md`).
+*
+* Pourquoi ici plutôt que recopié en eta : ces valeurs doivent coïncider EXACTEMENT
+* — l'URL du `.env` joint le port que le compose publie, et le README montre la
+* même. Trois littéraux séparés divergent au premier réglage, et l'écart ne se
+* voit qu'à la connexion refusée.
+*
+* ⚠️ **MySQL est publié sur 3306, pas 3307.** Le port décalé n'existait que pour
+* faire cohabiter MySQL et MariaDB dans un compose qui portait les deux ; une
+* app qui retient UN dialecte n'a plus rien avec quoi cohabiter, et un port
+* inattendu est une friction gratuite.
+*/
+const DATABASE_PARAMS = {
+	postgres: {
+		service: "postgres",
+		label: "PostgreSQL 16",
+		scheme: "postgres",
+		port: 5432,
+		image: "postgres:16-alpine"
+	},
+	mariadb: {
+		service: "mariadb",
+		label: "MariaDB 11.4",
+		scheme: "mysql",
+		port: 3306,
+		image: "mariadb:11.4"
+	},
+	mysql: {
+		service: "mysql",
+		label: "MySQL 8.4",
+		scheme: "mysql",
+		port: 3306,
+		image: "mysql:8.4"
+	}
+};
+/**
+* Compose le bloc `db` offert aux gabarits — `null` pour sqlite, qui n'a ni
+* service ni URL (le fichier vit dans `var/databases/`, l'ORM s'en charge seul).
+*/
+function resolveDatabase(choice, appName) {
+	if (choice === "sqlite") return null;
+	const params = DATABASE_PARAMS[choice];
+	const dsn = (database) => `${params.scheme}://${appName}:${appName}-dev@127.0.0.1:${params.port}/${database}`;
+	return {
+		choice,
+		...params,
+		database: appName,
+		databaseE2e: `${appName}_e2e`,
+		databaseScratch: `${appName}_e2e_scratch`,
+		url: dsn(appName),
+		urlE2e: dsn(`${appName}_e2e`),
+		urlScratch: dsn(`${appName}_e2e_scratch`)
+	};
+}
+/**
+* Racine du paquet `nodefony` contenant `templates/` — remontée depuis CE fichier
+* (source `src/cli/scaffold/`, bundle `dist/node/cli/scaffold/` : la remontée
+* marche pour les deux sans dépendre de la profondeur).
+*/
+function findPackageRoot() {
+	let dir = path.dirname(fileURLToPath(import.meta.url));
+	for (let i = 0; i < 7; i++) {
+		const manifest = path.join(dir, "package.json");
+		if (existsSync(manifest)) try {
+			if (JSON.parse(readFileSync(manifest, "utf8")).name === "nodefony") return dir;
+		} catch {}
+		const parent = path.dirname(dir);
+		if (parent === dir) break;
+		dir = parent;
+	}
+	throw new Error("paquet nodefony introuvable (templates/)");
+}
+/**
+* Workspaces nodefony d'un CHECKOUT du repo (`src/nodefony` + `src/packages/@nodefony/*`),
+* résolus depuis la racine du paquet `nodefony`. Un paquet INSTALLÉ (node_modules)
+* n'a pas ce voisinage → `null` (le mode link n'a de sens que sur un checkout).
+*/
+function resolveLocalWorkspaces(packageRoot) {
+	const packagesDir = path.resolve(packageRoot, "..", "packages", "@nodefony");
+	if (!existsSync(packagesDir)) return null;
+	const map = { nodefony: packageRoot };
+	for (const entry of readdirSync(packagesDir, { withFileTypes: true })) if (entry.isDirectory()) map[`@nodefony/${entry.name}`] = path.join(packagesDir, entry.name);
+	return map;
+}
+/**
+* Mode link : réécrit dans le `package.json` GÉNÉRÉ toute dep `nodefony` /
+* `@nodefony/*` en `file:<workspace>` — `npm install` symlinke le checkout local
+* et installe ses deps transitives. Rend l'app contrôlable AVANT toute release
+* npm (dev du framework) ; les deps publiques (zod, react…) restent au registre.
+*
+* @returns les noms de paquets liés (triés, pour le récap)
+* @throws si une dep du scope nodefony n'existe pas dans le checkout
+*/
+function linkLocalDeps(destDir, workspaces, writer) {
+	const manifestPath = path.join(destDir, "package.json");
+	const manifest = JSON.parse(writer.read(manifestPath));
+	const linked = [];
+	for (const block of ["dependencies", "devDependencies"]) {
+		const deps = manifest[block];
+		if (!deps) continue;
+		for (const name of Object.keys(deps)) {
+			if (name !== "nodefony" && !name.startsWith("@nodefony/")) continue;
+			const workspace = workspaces[name];
+			if (!workspace) throw new Error(`link : workspace introuvable pour ${name}`);
+			deps[name] = `file:${workspace.split(path.sep).join("/")}`;
+			linked.push(name);
+		}
+	}
+	writer.write(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`);
+	return linked.sort();
+}
+/**
+* Complète et VALIDE des réponses partielles contre la spec d'un type : défauts
+* appliqués, patterns vérifiés, choix contraints à leur liste. Le contexte des
+* templates est donc complet PAR CONSTRUCTION (eta ne rend jamais un `undefined`
+* silencieux). Les questions `askIf` non satisfaites sont forcées à `false` ;
+* celles dont l'`askWhen` n'est pas satisfait retombent à leur DÉFAUT — une
+* réponse qui porte sur ce qui ne sera pas généré n'a rien à décider.
+*
+* L'ordre de la spec fait foi : une question `askWhen` lit la réponse DÉJÀ
+* résolue de celle qu'elle désigne, donc cette dernière doit la précéder.
+*
+* @throws Error si une valeur viole la spec (message = libellé + attendu)
+*/
+function resolveAnswers(spec, partial, caps) {
+	const answers = {};
+	for (const q of spec.questions) {
+		let value = partial[q.key];
+		if (q.askIf === "hasCheckout" && !caps.hasCheckout) value = false;
+		if (q.askWhen && String(answers[q.askWhen.key]) !== q.askWhen.equals) value = void 0;
+		if (value === void 0) value = q.default;
+		if (q.type === "boolean") {
+			answers[q.key] = value === true || value === "true";
+			continue;
+		}
+		if (q.type === "list") {
+			answers[q.key] = Array.isArray(value) ? value.map(String).filter((v) => v.length > 0) : typeof value === "string" && value.length > 0 ? [value] : [];
+			continue;
+		}
+		const str = String(value);
+		if (q.type === "choice") {
+			if (!q.choices?.some((c) => c.value === str)) {
+				const allowed = q.choices?.map((c) => c.value).join(" | ") ?? "";
+				throw new Error(`${q.key} invalide « ${str} » — attendu : ${allowed}`);
+			}
+		}
+		if (q.pattern && !new RegExp(q.pattern, "u").test(str)) throw new Error(`${q.key} invalide « ${str} » — ${q.patternHint ?? q.pattern}`);
+		answers[q.key] = str;
+	}
+	return answers;
+}
+/**
+* Rend un layer de templates (`*.tpl`) dans `destDir` via eta. Les noms de
+* fichiers peuvent porter des TOKENS (`__NAME__Controller.ts.tpl`) remplacés
+* par `tokens` — un template ne peut pas mettre de tag eta dans un nom de
+* fichier, le token est l'équivalent côté chemin.
+*/
+function renderLayer(eta, srcDir, destDir, data, written, writer, tokens) {
+	const entries = readdirSync(srcDir, {
+		withFileTypes: true,
+		recursive: true
+	});
+	for (const entry of entries) {
+		if (!entry.isFile() || !entry.name.endsWith(".tpl")) continue;
+		const abs = path.join(entry.parentPath, entry.name);
+		let relDir = path.relative(srcDir, entry.parentPath);
+		const segments = relDir.split(path.sep);
+		const mapped = segments[0] !== void 0 && DIR_RENAMES[segments[0]];
+		if (mapped) relDir = path.join(mapped, ...segments.slice(1));
+		const base = entry.name.replace(/\.tpl$/u, "");
+		let rel = path.join(relDir, RENAMES[base] ?? base);
+		for (const [token, value] of Object.entries(tokens ?? {})) rel = rel.replaceAll(token, value);
+		const rendered = eta.renderString(readFileSync(abs, "utf8"), data);
+		if (rendered.includes("<%")) throw new Error(`tag eta résiduel dans ${rel}`);
+		if (rendered.trim() === "") continue;
+		writer.write(path.join(destDir, rel), rendered);
+		written.push(rel);
+	}
+}
+/** Marqueurs de la zone préservée d'`AGENTS.md` — le contrat du merge borné. */
+const APP_NOTES_START = "<!-- app-notes:start -->";
+const APP_NOTES_END = "<!-- app-notes:end -->";
+/**
+* Réinjecte la zone `app-notes` du contenu précédent dans le rendu neuf.
+*
+* C'est TOUT le merge que le scaffold sait faire, et c'est voulu : `AGENTS.md`
+* est 100 % dérivé (réécrit en entier à chaque régénération — il ne peut pas
+* mentir), SAUF cette zone, où l'humain et l'agent accumulent les leçons
+* propres à l'app. Un marqueur absent ou inversé (fichier retravaillé à la
+* main) → le rendu neuf part tel quel : mieux vaut perdre des notes déplacées
+* qu'écrire un fichier recousu de façon imprévisible.
+*/
+function preserveAppNotes(previous, next) {
+	const start = previous.indexOf(APP_NOTES_START);
+	const end = previous.indexOf(APP_NOTES_END);
+	if (start === -1 || end === -1 || end < start) return next;
+	const notes = previous.slice(start + 24, end);
+	const ns = next.indexOf(APP_NOTES_START);
+	const ne = next.indexOf(APP_NOTES_END);
+	if (ns === -1 || ne === -1 || ne < ns) return next;
+	return next.slice(0, ns + 24) + notes + next.slice(ne);
+}
+/**
+* Rend `AGENTS.md` (+ le pointeur `CLAUDE.md`) à la racine du projet.
+*
+* Appelé par `create app` ET re-appelé par les scaffolds in-project qui
+* changent l'inventaire décrit (`create module`) : régénération BORNÉE —
+* réécriture complète depuis l'état RÉEL du projet, seule la zone `app-notes`
+* est réinjectée (cf {@link preserveAppNotes}). Le moteur ne sait pas rejouer
+* des templates sur de l'existant, et n'essaie pas : seuls ces fichiers
+* 100 % dérivés sont régénérables.
+*
+* `CLAUDE.md` n'est écrit QUE s'il n'existe pas : c'est un pointeur d'une
+* ligne, et un `CLAUDE.md` remplacé par l'utilisateur lui appartient.
+*/
+function renderProjectAgents(eta, packageRoot, projectRoot, data, written, writer) {
+	const tplDir = path.join(packageRoot, "templates", "app", "agents");
+	const agentsPath = path.join(projectRoot, "AGENTS.md");
+	let rendered = eta.renderString(readFileSync(path.join(tplDir, "AGENTS.md.tpl"), "utf8"), data);
+	if (rendered.includes("<%")) throw new Error("tag eta résiduel dans AGENTS.md");
+	if (writer.exists(agentsPath)) rendered = preserveAppNotes(writer.read(agentsPath), rendered);
+	writer.write(agentsPath, rendered);
+	written.push("AGENTS.md");
+	const template = readFileSync(path.join(tplDir, "POINTEUR.md.tpl"), "utf8");
+	for (const { file, agents } of pointeursInstructions(data.agents)) {
+		const target = path.join(projectRoot, file);
+		if (writer.exists(target)) continue;
+		const pointer = eta.renderString(template, {
+			...data,
+			pointeur: file,
+			agents: agents.join(" et ")
+		});
+		writer.write(target, pointer);
+		written.push(file);
+	}
+}
+/**
+* Pose le fichier-POINTEUR d'instructions des agents donnés, s'il manque.
+*
+* Extrait de {@link renderProjectAgents} pour être appelable AILLEURS : c'est
+* `nodefony ai:mcp --agent <clé>` qui câble un agent après la création de
+* l'application, et c'est donc là que son pointeur doit apparaître. Sans cette
+* fonction, filtrer les pointeurs à la création (pour ne plus déposer un
+* `GEMINI.md` chez qui a demandé Claude) aurait privé de son fichier tout agent
+* ajouté ensuite — on aurait remplacé un défaut par un autre.
+*
+* Un pointeur DÉJÀ présent n'est jamais réécrit : celui qu'un développeur a
+* remplacé lui appartient.
+*
+* @param projectRoot - racine de l'application.
+* @param keys - clés des agents concernés.
+* @param appName - nom de l'application (rendu dans le gabarit).
+* @returns les fichiers réellement écrits, relatifs à la racine.
+*/
+function writeAgentPointers(projectRoot, keys, appName) {
+	const pointeurs = pointeursInstructions(keys);
+	if (pointeurs.length === 0) return [];
+	const tplDir = path.join(findPackageRoot(), "templates", "app", "agents");
+	const template = readFileSync(path.join(tplDir, "POINTEUR.md.tpl"), "utf8");
+	const eta = new Eta({ autoEscape: false });
+	const written = [];
+	for (const { file, agents } of pointeurs) {
+		const target = path.join(projectRoot, file);
+		try {
+			writeFileSync(target, eta.renderString(template, {
+				appName,
+				pointeur: file,
+				agents: agents.join(" et ")
+			}), {
+				encoding: "utf8",
+				flag: "wx"
+			});
+		} catch (err) {
+			if (err.code === "EEXIST") continue;
+			throw err;
+		}
+		written.push(file);
+	}
+	return written;
+}
+/**
+* Cibles de scaffold du projet : l'app racine + les modules locaux
+* (`modules/<x>/` portant `package.json` + `index.ts` — le layout produit par
+* `create module`). Consommée par le CLI (validation `--module`) et par le
+* futur formulaire Studio (liste de choix dynamique par projet).
+*/
+/**
+* Capacités de l'environnement, telles que le MOTEUR les voit.
+*
+* Sert aux questions conditionnelles (`askIf`) : `link` (créer une app branchée sur le
+* checkout local du framework, au lieu des paquets npm publiés) n'a de sens que si un
+* checkout est résolvable. Un front ne peut PAS le deviner — seul le serveur sait ce
+* qu'il y a sur le disque. Le figer côté client à `false` reviendrait à supprimer
+* l'option en silence.
+*
+* @returns les capacités passées à {@link resolveAnswers}.
+*/
+function scaffoldCaps() {
+	return { hasCheckout: resolveLocalWorkspaces(findPackageRoot()) !== null };
+}
+/**
+* Lit le contexte du projet contenant `dir`.
+*
+* @param dir - un dossier quelconque du projet (la racine est retrouvée seule).
+* @param writer - accès fichiers (injectable pour les tests).
+* @returns le contexte, ou `null` si `dir` n'est pas dans un projet Nodefony.
+*/
+function getScaffoldContext(dir, writer = new ScaffoldWriter()) {
+	const projectRoot = findProjectRoot(dir);
+	if (!projectRoot) return null;
+	const targets = listTargets(projectRoot, writer);
+	const entities = {};
+	for (const target of targets) entities[target.name] = readEntities(target.dir, writer);
+	return {
+		targets,
+		connectors: readConnectors(projectRoot, writer),
+		columnTypes: describeColumnTypes(),
+		entities,
+		idKinds: ENTITY_ID_KINDS
+	};
+}
+function listTargets(projectRoot, writer = new ScaffoldWriter()) {
+	const readName = (dir) => {
+		try {
+			return JSON.parse(writer.read(path.join(dir, "package.json"))).name ?? null;
+		} catch {
+			return null;
+		}
+	};
+	let rootManifest = {};
+	try {
+		rootManifest = JSON.parse(writer.read(path.join(projectRoot, "package.json")));
+	} catch {}
+	const targets = [{
+		kind: "app",
+		name: rootManifest.name ?? path.basename(projectRoot),
+		dir: projectRoot
+	}];
+	const layout = resolveModuleLayout(rootManifest, path.basename(projectRoot));
+	for (const rel of layout.targetDirs) {
+		const modulesDir = path.join(projectRoot, ...rel.split("/"));
+		if (!writer.exists(modulesDir)) continue;
+		for (const entry of writer.listDir(modulesDir)) {
+			const dir = path.join(modulesDir, entry.name);
+			if (!entry.isDirectory || !writer.exists(path.join(dir, "index.ts"))) continue;
+			targets.push({
+				kind: "module",
+				name: readName(dir) ?? entry.name,
+				dir
+			});
+		}
+	}
+	return targets;
+}
+/**
+* Résout la cible d'un scaffold in-project : l'application, ou le module
+* désigné par `--module`.
+*
+* Un module a DEUX identités — son **nom npm** (`@app/blog`, celui qui vit dans
+* son manifeste et dans celui de l'app) et son **dossier** (`blog`, celui qu'on
+* a tapé pour le créer). N'accepter que le premier faisait échouer
+* `--module blog` juste après un `create module blog` : mesuré sur un agent
+* tiers, trois tentatives perdues sur cette seule asymétrie, alors que le nom
+* court est celui que l'utilisateur a en tête.
+*
+* Le nom court est donc accepté **quand il désigne UNE cible**. Ambigu, il est
+* refusé en nommant les candidats plutôt qu'en en choisissant un : un dépôt à
+* plusieurs dossiers de workspaces peut porter `packages/@x/auth` ET
+* `modules/auth` — deux modules distincts, même nom court. Le nom npm exact
+* l'emporte toujours, et reste la façon de lever l'ambiguïté.
+*
+* @param projectRoot - racine de l'application (porte `nodefony.config.ts`).
+* @param moduleName - valeur de `--module` ; vide = l'application elle-même.
+* @param writer - accès disque injecté (simulation `--dry-run` comprise).
+* @returns la cible résolue.
+* @throws si le nom ne désigne aucune cible, ou s'il en désigne plusieurs.
+*/
+function resolveScaffoldTarget(projectRoot, moduleName, writer) {
+	const targets = listTargets(projectRoot, writer);
+	const app = targets[0];
+	if (!moduleName) return app;
+	const modules = targets.filter((t) => t.kind === "module");
+	const exact = modules.find((t) => t.name === moduleName);
+	if (exact) return exact;
+	const short = modules.filter((t) => path.basename(t.dir) === moduleName);
+	if (short.length === 1) return short[0];
+	if (short.length > 1) throw new Error(`« ${moduleName} » désigne ${short.length} modules — reprends le nom complet : ${short.map((t) => t.name).join(" · ")}`);
+	const known = targets.map((t) => `${t.name} (${t.kind})`).join(" · ");
+	throw new Error(`module « ${moduleName} » introuvable — cibles du projet : ${known}`);
+}
+/** `blog-post` / `BlogPost` / `blogPost` → `BlogPost`. */
+function toPascalCase(name) {
+	return name.split(/[-_\s]+/u).filter(Boolean).map((w) => w[0].toUpperCase() + w.slice(1)).join("");
+}
+/** `BlogPost` / `blog_post` → `blog-post`. */
+function toKebabCase(name) {
+	return name.replace(/([a-z0-9])([A-Z])/gu, "$1-$2").replaceAll("_", "-").toLowerCase();
+}
+/**
+* Câble une classe générée dans le décorateur-liste de l'`index.ts` cible
+* (`@controllers([...])`, `@entities([...])`, `@services([...])`) : ajoute
+* l'import après le dernier import existant + insère le nom dans le tableau du
+* décorateur. Édition TEXTUELLE gardée — toute ambiguïté = throw actionnable,
+* jamais un fichier corrompu (le fichier n'est écrit que si les insertions
+* tiennent).
+*
+* `controllers`/`entities` sont TOUJOURS rendus par les scaffolds qui les
+* consomment (`@controllers([])` inconditionnel dans `app`/`module` ; les
+* entités passent par {@link wireEntitiesDecorator}, qui crée déjà sa propre
+* liste) — le décorateur introuvable y reste un refus. `services` diffère : le
+* layer `module/base` ne le rend que si la question « service » a répondu
+* `true`, et la racine d'une app n'en déclare JAMAIS un — le cas nominal d'un
+* `create service` est donc une cible qui n'a PAS encore de `@services([...])`.
+* Pour ce seul décorateur, l'absence n'est pas un refus : on le CRÉE, juste
+* au-dessus de la classe (même position que le gabarit quand il le rend lui-même),
+* en import ant `services` depuis `"nodefony"` s'il ne l'est pas déjà.
+*
+* @throws si la classe y est déjà, si aucun import n'ancre l'insertion, ou —
+*   pour `controllers`/`entities` seulement — si le décorateur est introuvable
+*   (le message donne l'édition manuelle exacte).
+*/
+/**
+* L'expression d'un décorateur-liste RÉEL — jamais sa mention dans un commentaire.
+*
+* `String.replace` sans `g` réécrit la PREMIÈRE occurrence trouvée. Un `index.ts`
+* dont le TSDoc cite `@services([…])` au-dessus de la classe — ce que fait le
+* gabarit d'application, pour expliquer à quoi sert la liste — voyait donc sa
+* PROSE réécrite : `@services([…, DiscountService]) est ce qui fait EXISTER un
+* service`, phrase absurde qui s'allongeait à chaque service créé, pendant que
+* le vrai décorateur, lui, était bien étendu (constaté sur un run du banc).
+*
+* L'ancre `^[ \t]*@` suffit à trancher : une ligne de TSDoc commence par ` * `.
+* Le premier groupe capture l'indentation pour la rendre telle quelle — un
+* décorateur de classe imbriquée n'a pas à être désaligné par sa réécriture.
+*
+* @param decorator - le décorateur-liste visé.
+* @returns l'expression, multi-lignes, avec l'indentation en groupe 1 et le
+*   contenu de la liste en groupe 2.
+*/
+function decoratorListRe(decorator) {
+	return new RegExp(`^([ \\t]*)@${decorator}\\(\\[([^\\]]*)\\]\\)`, "mu");
+}
+function wireDecoratorList(indexPath, decorator, className, importPath, writer) {
+	const source = writer.read(indexPath);
+	if (new RegExp(`\\b${className}\\b`, "u").test(source)) throw new Error(`${className} est déjà référencé dans ${indexPath} — choisis un autre nom`);
+	const importLine = `import ${className} from "${importPath}";`;
+	const last = [...source.matchAll(/^import [^\n]*$/gmu)].at(-1);
+	if (!last || last.index === void 0) throw new Error(`aucun import trouvé dans ${indexPath} — ajoute à la main :\n  ${importLine}\n  @${decorator}([..., ${className}])`);
+	const importAt = last.index + last[0].length;
+	const extraImport = decorator === "services" && !/\bservices\b[^\n]*from "nodefony"/u.test(source) ? `\nimport { services } from "nodefony";` : "";
+	const withImport = source.slice(0, importAt) + `\n${importLine}${extraImport}` + source.slice(importAt);
+	const decoRe = decoratorListRe(decorator);
+	const match = decoRe.exec(withImport);
+	if (match && match.index !== void 0) {
+		const list = match[2].trim();
+		const wired = withImport.replace(decoRe, `$1@${decorator}([${list ? `${list.replace(/,\s*$/u, "")}, ` : ""}${className}])`);
+		writer.write(indexPath, wired);
+		return;
+	}
+	if (decorator !== "services") throw new Error(`@${decorator}([...]) introuvable dans ${indexPath} — ajoute à la main :\n  ${importLine}\n  @${decorator}([${className}]) sur la classe Module`);
+	const classMatch = /^(?:export\s+(?:default\s+)?)?class\s+\w+\s+extends\s+Module\b/mu.exec(withImport);
+	if (!classMatch || classMatch.index === void 0) throw new Error(`« class … extends Module » introuvable dans ${indexPath} — ajoute à la main :\n  ${importLine}\n  @services([${className}]) juste au-dessus de la classe`);
+	const wired = withImport.slice(0, classMatch.index) + `@services([${className}])\n` + withImport.slice(classMatch.index);
+	writer.write(indexPath, wired);
+}
+/**
+* Exécute un scaffold — point d'entrée UNIQUE des trois fronts (CLI rapide,
+* CLI interactif, Studio), dispatché par type :
+*  - `app` : projet NEUF dans `request.dir` (layers base/preset/frontend) ;
+*  - `controller` : IN-PROJECT — `request.dir` est le point de départ de la
+*    détection de racine (cwd de l'appelant), la cible réelle vient de
+*    `answers.module` (vide = app racine).
+*
+* Toutes les écritures passent par une TRANSACTION ({@link ScaffoldWriter}) que
+* seul le scaffold RACINE vide sur disque, une fois toutes les étapes passées :
+* un refus, même tardif, ne laisse donc jamais de projet à moitié modifié. Et
+* comme la simulation n'est que « la même exécution sans vidage », `dryRun`
+* décrit exactement ce qui se passerait — pas ce qu'un second code de
+* prévision croirait.
+*
+* @returns fichiers écrits + paquets liés — l'appelant décide du rendu (CLI ou JSON)
+* @throws Error si réponses invalides, dossier non vide sans force, ou template cassé
+*/
+function runScaffold(request, version, options = {}) {
+	const writer = options.writer ?? new ScaffoldWriter();
+	const result = dispatchScaffold(request, version, writer);
+	if (options.writer) return result;
+	const forme = formatScaffoldOutput(writer, result.dest);
+	const rendered = forme.pending > 0 ? {
+		...result,
+		unformatted: forme.pending
+	} : result;
+	if (options.dryRun) return {
+		...rendered,
+		changes: writer.changes()
+	};
+	writer.commit();
+	return rendered;
+}
+/** Résout la spec puis route vers le scaffold du type demandé. */
+function dispatchScaffold(request, version, writer) {
+	const [spec] = getScaffoldSpec(request.type);
+	if (!spec) throw new Error(`type de scaffold inconnu : ${request.type}`);
+	const packageRoot = findPackageRoot();
+	const workspaces = resolveLocalWorkspaces(packageRoot);
+	const answers = resolveAnswers(spec, request.answers, { hasCheckout: workspaces !== null });
+	if (request.type === "module") return runModuleScaffold(request, answers, packageRoot, version, writer);
+	if (request.type === "controller") return runControllerScaffold(request, answers, packageRoot, writer);
+	if (request.type === "service") return runServiceScaffold(request, answers, packageRoot, writer);
+	if (request.type === "front") return runFrontScaffold(request, answers, packageRoot, writer);
+	if (request.type === "entity") return runEntityScaffold(request, answers, packageRoot, writer);
+	if (request.type === "command") return runCommandScaffold(request, answers, packageRoot, writer);
+	const dest = path.resolve(request.dir);
+	if (existsSync(dest) && readdirSync(dest).length > 0 && !request.force) throw new Error(`le dossier ${dest} existe et n'est pas vide (--force pour écraser)`);
+	const preset = answers.preset;
+	const frontend = answers.frontend;
+	const front = frontend !== "none" ? FRONTEND_PARAMS[frontend] : null;
+	const db = resolveDatabase(answers.database, String(answers.name));
+	const data = {
+		appName: answers.name,
+		dialect: answers.database === "postgres" ? "postgres" : answers.database === "sqlite" || !answers.database ? "sqlite" : "mysql",
+		pascal: toPascalCase(String(answers.name)),
+		entryName: answers.name,
+		nodefonyVersion: version,
+		pkg: SCAFFOLD_VERSIONS,
+		preset,
+		complete: preset === "complete",
+		hasSecurity: preset === "complete",
+		hasOrm: preset === "complete",
+		frontend,
+		front,
+		db,
+		secrets: {
+			NF_TOTP_KEY: randomBytes(32).toString("base64"),
+			NF_WEBHOOK_KEY: randomBytes(32).toString("base64"),
+			NF_CSRF_SECRET: randomBytes(32).toString("base64")
+		}
+	};
+	const eta = new Eta(ETA_OPTIONS);
+	const templates = path.join(packageRoot, "templates", request.type);
+	const written = [];
+	renderLayer(eta, path.join(templates, "base"), dest, data, written, writer);
+	if (!front) renderLayer(eta, path.join(templates, "home"), dest, data, written, writer);
+	renderLayer(eta, path.join(packageRoot, "templates", "controller", "hello"), dest, {
+		nameClass: "HelloController",
+		kebab: "hello",
+		route: "/api",
+		indexPath: "/hello",
+		helloName: answers.name,
+		secureRoute: preset === "complete"
+	}, written, writer, { __NAME__: "HelloController" });
+	if (preset === "complete") {
+		renderLayer(eta, path.join(templates, "complete"), dest, data, written, writer);
+		renderLayer(eta, path.join(packageRoot, "templates", "controller", "realtime"), dest, {
+			nameClass: "LiveController",
+			kebab: "live",
+			route: "/api/live",
+			channel: "live",
+			hasSecurity: true
+		}, written, writer, {
+			__NAME__: "LiveController",
+			__KEBAB__: "live"
+		});
+	}
+	if (front) {
+		renderLayer(eta, path.join(packageRoot, "templates", "shared", "front-shell"), dest, data, written, writer);
+		renderLayer(eta, path.join(templates, "frontend", "shared"), dest, data, written, writer);
+		renderLayer(eta, path.join(packageRoot, "templates", "shared", "front-entry", frontend), dest, data, written, writer);
+		renderLayer(eta, path.join(packageRoot, "templates", "shared", "front-registrar"), dest, data, written, writer, { __PASCAL__: toPascalCase(String(answers.name)) });
+		renderLayer(eta, path.join(templates, "frontend", frontend), dest, data, written, writer);
+		if (frontend === "angular") renderLayer(eta, path.join(packageRoot, "templates", "shared", "ng-app-tsconfig"), dest, data, written, writer);
+		if (frontend === "vue") renderLayer(eta, path.join(packageRoot, "templates", "shared", "vue-shim"), dest, data, written, writer);
+		if (frontend === "svelte") renderLayer(eta, path.join(packageRoot, "templates", "shared", "svelte-shim"), dest, data, written, writer);
+	}
+	const chosenAgents = Array.isArray(answers.agents) ? answers.agents : [];
+	renderProjectAgents(eta, packageRoot, dest, {
+		appName: String(answers.name),
+		nodefonyVersion: version,
+		hasSecurity: preset === "complete",
+		hasOrm: preset === "complete",
+		hasRealtime: preset === "complete",
+		hasStudio: preset === "complete",
+		front: front !== null,
+		hasMigrateRecipe: writer.exists(path.join(dest, "deploy", "migrate-job.yaml")),
+		modules: [],
+		agents: chosenAgents
+	}, written, writer);
+	let linked = [];
+	if (answers.link === true) {
+		if (!workspaces) throw new Error("link exige un CHECKOUT de nodefony-core (paquet installé détecté) — sans checkout, attends la release npm puis installe sans --link");
+		linked = linkLocalDeps(dest, workspaces, writer);
+	}
+	return {
+		dest,
+		files: written.sort(),
+		linked
+	};
+}
+/**
+* Déclare `modules/*` en workspaces npm de l'app et branche les scripts sur eux.
+*
+* POURQUOI c'est indispensable : le Kernel charge un module par son NOM
+* (`import("@app/blog")`, cf `Kernel.loadModule`) — pas par un chemin. Sans le
+* symlink que npm pose pour un workspace, le boot échoue sur « Cannot find
+* package ». Les scripts sont chaînés dans la foulée, sinon le module ne serait
+* ni construit (le bundler de l'app ne regarde que `index.ts` + `nodefony/**`),
+* ni typé, ni testé : du code mort au premier jour.
+*
+* Idempotent — relancé pour le 2ᵉ module, il ne touche plus à rien.
+*
+* @returns true si le `package.json` de l'app a été modifié.
+*/
+function ensureWorkspaces(projectRoot, writer) {
+	const manifestPath = path.join(projectRoot, "package.json");
+	const manifest = JSON.parse(writer.read(manifestPath));
+	let changed = false;
+	const workspaces = manifest.workspaces ?? [];
+	if (!workspaces.includes("modules/*")) {
+		manifest.workspaces = [...workspaces, "modules/*"];
+		changed = true;
+	}
+	const scripts = manifest.scripts ??= {};
+	for (const [name, when] of Object.entries({
+		build: "before",
+		typecheck: "after",
+		test: "after"
+	})) {
+		const script = scripts[name];
+		if (!script || script.includes("--workspaces")) continue;
+		const delegated = `npm run ${name} --workspaces --if-present`;
+		scripts[name] = when === "before" ? `${delegated} && ${script}` : `${script} && ${delegated}`;
+		changed = true;
+	}
+	if (changed) writer.write(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`);
+	return changed;
+}
+/**
+* Ajoute le module au manifeste `modules` de `nodefony.config.ts` — c'est CE
+* tableau qui décide de ce qui se charge, et dans quel ordre. Un module local
+* vient à la fin : le socle (http, framework, security…) doit être debout avant.
+*
+* Édition textuelle GARDÉE (même doctrine que `wireDecoratorList`) : on n'écrit
+* que si l'ancre est trouvée sans ambiguïté, sinon on rend une note actionnable —
+* jamais un `nodefony.config.ts` corrompu, qui empêcherait l'app de booter.
+*
+* @param moduleDir - dossier où le module a été créé, relatif à la racine (en
+*   `/`) — seulement pour NOMMER le bon endroit dans le commentaire inséré.
+* @returns note à afficher si un geste manuel reste nécessaire, sinon `null`.
+*/
+function wireModuleManifest(configPath, pkgName, writer, moduleDir = "modules") {
+	const manual = `ajoute à la main dans le manifeste modules de nodefony.config.ts :\n  use("${pkgName}", {}),`;
+	if (!writer.exists(configPath)) return manual;
+	const source = writer.read(configPath);
+	if (source.includes(`"${pkgName}"`)) return null;
+	const anchor = /modules\s*:\s*\[/u.exec(source);
+	if (!anchor || anchor.index === void 0) return manual;
+	let depth = 0;
+	let close = -1;
+	for (let i = anchor.index + anchor[0].length - 1; i < source.length; i++) {
+		const char = source[i];
+		if (char === "[") depth++;
+		else if (char === "]") {
+			depth--;
+			if (depth === 0) {
+				close = i;
+				break;
+			}
+		}
+	}
+	if (close === -1) return manual;
+	const entry = /import\s*\{[^}]*\buse\b[^}]*\}\s*from\s*"nodefony"/u.test(source) ? `use("${pkgName}", {}),` : `"${pkgName}",`;
+	const comment = `// Module local du projet (${moduleDir}/) — créé par \`nodefony create module\`.`;
+	writer.write(configPath, `${source.slice(0, close).trimEnd()}\n\n    ${comment}\n    ${entry}\n  ${source.slice(close)}`);
+	return null;
+}
+/**
+* Déclare un rôle applicatif sous `ROLE_ADMIN` dans la hiérarchie de l'app.
+*
+* ## Pourquoi la hiérarchie, et pas une liste de rôles sur l'action
+*
+* Deux gestes rendent la même réponse sur la route qu'on vient d'écrire — une
+* hiérarchie, ou `@IsGranted(["ROLE_X", "ROLE_ADMIN"])`. Un seul GÉNÉRALISE :
+* la hiérarchie vaut pour toute route future gardée par ce rôle, la liste
+* s'arrête à cette action-là et devra être recopiée à chaque fois. Le troisième
+* geste — attribuer le rôle à l'administrateur au semis — est pire encore : il
+* ne se voit dans aucun diff de route et se perd au premier compte recréé.
+*
+* ## Ce que cette fonction n'invente pas
+*
+* Elle n'ajoute JAMAIS une clé `roleHierarchy` absente, ni un `ROLE_ADMIN`
+* absent : composer un bloc de configuration à l'aveugle dans un fichier que
+* l'utilisateur a pu réorganiser produirait un manifeste qui ne boote plus.
+* Quand l'ancre manque, elle rend la note à taper — même doctrine que
+* {@link wireModuleManifest} et `wireDecoratorList`.
+*
+* @param configPath - `nodefony.config.ts` de l'application.
+* @param role - le rôle à déclarer (déjà validé par le schéma de la question).
+* @param writer - écrivain du scaffold (respecte `--dry-run`).
+* @returns note à afficher si un geste manuel reste nécessaire, sinon `null`.
+*/
+function wireRoleHierarchy(configPath, role, writer) {
+	const manual = `ajoute à la main dans roleHierarchy de nodefony.config.ts :\n  ROLE_ADMIN: ["ROLE_USER", "${role}"],\n  (sans quoi un administrateur devra porter « ${role} » pour accéder à ce controller)`;
+	if (!writer.exists(configPath)) return manual;
+	const source = writer.read(configPath);
+	const block = /roleHierarchy\s*:\s*\{/u.exec(source);
+	if (!block || block.index === void 0) return manual;
+	let depth = 0;
+	let close = -1;
+	for (let i = block.index + block[0].length - 1; i < source.length; i++) {
+		const char = source[i];
+		if (char === "{") depth++;
+		else if (char === "}") {
+			depth--;
+			if (depth === 0) {
+				close = i;
+				break;
+			}
+		}
+	}
+	if (close === -1) return manual;
+	const body = source.slice(block.index, close);
+	if (body.includes(`"${role}"`)) return null;
+	const admin = /(ROLE_ADMIN\s*:\s*\[)([^\]]*)(\])/u.exec(body);
+	if (!admin || admin.index === void 0) return manual;
+	const inner = (admin[2] ?? "").replace(/,\s*$/u, "");
+	const separator = inner.trim().length > 0 ? ", " : "";
+	const replacement = `${admin[1]}${inner}${separator}"${role}"${admin[3]}`;
+	const patchedBody = body.slice(0, admin.index) + replacement + body.slice(admin.index + admin[0].length);
+	writer.write(configPath, source.slice(0, block.index) + patchedBody + source.slice(close));
+	return null;
+}
+/**
+* Noms des paquets que l'APPLICATION déclare (`dependencies` + `devDependencies`).
+*
+* Source unique des deux scaffolds qui doivent savoir si une brique du framework
+* est installée : `create module` (refus AVANT écriture quand elle manque) et
+* `create front` (qui pose la peer sur un module local quand l'app, elle, l'a).
+*
+* @param projectRoot - racine de l'application (porte `nodefony.config.ts`).
+* @returns l'ensemble des noms déclarés — jamais les versions, seule la présence
+*   est une information ici.
+*/
+function readAppDependencyNames(projectRoot, writer) {
+	const manifest = JSON.parse(writer.read(path.join(projectRoot, "package.json")));
+	return /* @__PURE__ */ new Set([...Object.keys(manifest.dependencies ?? {}), ...Object.keys(manifest.devDependencies ?? {})]);
+}
+/**
+* Scaffold IN-PROJECT d'un module applicatif : un WORKSPACE npm sous
+* `modules/<nom>/` (package.json + build rolldown + config Zod + tests + docs),
+* déclaré dans les workspaces de l'app et dans le manifeste `modules`.
+*
+* Ce scaffold pose la COQUILLE et rien d'autre : le controller et le frontend
+* éventuels sont rendus par les scaffolds `controller` et `front` EXISTANTS,
+* ciblés sur le module fraîchement créé. Aucun template n'est dupliqué — la
+* commande qui sait poser un controller reste la seule à savoir le faire.
+*
+* @throws hors projet, module déjà présent (sans `--force`), nom en collision,
+*   ou brique manquante dans l'app (realtime/frontend) — avec le geste exact.
+*/
+function runModuleScaffold(request, answers, packageRoot, version, writer) {
+	const projectRoot = findProjectRoot(request.dir);
+	if (!projectRoot) throw new Error("aucun projet Nodefony ici (nodefony.config.ts introuvable en remontant) — lance la commande depuis une app (créée par `nodefony create app`)");
+	const name = toKebabCase(String(answers.name));
+	const appManifestPath = path.join(projectRoot, "package.json");
+	const appManifest = JSON.parse(writer.read(appManifestPath));
+	const appName = appManifest.name ?? path.basename(projectRoot);
+	const layout = resolveModuleLayout(appManifest, path.basename(projectRoot));
+	const dest = path.join(projectRoot, ...layout.createDir.split("/"), name);
+	if (writer.exists(dest) && writer.listDir(dest).length > 0 && !request.force) throw new Error(`le module ${name} existe déjà (${layout.createDir}/${name}) — choisis un autre nom, ou --force`);
+	const pkgName = `${layout.scope}/${name}`;
+	const appDeps = readAppDependencyNames(projectRoot, writer);
+	const controller = String(answers.controller);
+	const frontend = answers.frontend;
+	if ((controller === "realtime" || controller === "duplex") && !appDeps.has("@nodefony/realtime")) throw new Error(`le controller ${controller} exige @nodefony/realtime, absent de l'app — ajoute la dep + use("@nodefony/realtime") au manifeste, ou --controller hello`);
+	if (frontend !== "none" && !appDeps.has("@nodefony/frontend")) throw new Error("un frontend exige @nodefony/frontend, absent de l'app — ajoute la dep + \"@nodefony/frontend\" au manifeste, ou --frontend none");
+	const pascal = toPascalCase(name);
+	const data = {
+		name,
+		pkgName,
+		appName,
+		pascal,
+		camel: pascal[0].toLowerCase() + pascal.slice(1),
+		upper: name.replaceAll("-", "_").toUpperCase(),
+		description: String(answers.description) || `Module ${name} de ${appName}`,
+		nodefonyVersion: version,
+		pkg: SCAFFOLD_VERSIONS,
+		service: answers.service === true,
+		command: answers.command === true,
+		controller,
+		needsRealtime: controller === "realtime" || controller === "duplex",
+		frontend,
+		front: frontend !== "none" ? FRONTEND_PARAMS[frontend] : null,
+		/**
+		* Le module naît-il paquet PUBLIABLE (surface npm : `exports`, `types`,
+		* `files`, peerDependencies, `.d.ts` générés) ou module local privé ?
+		* Décidé par le layout du dépôt, pas par une option — c'est une propriété du
+		* dossier où il atterrit.
+		*/
+		publishable: layout.kind === "packages",
+		/** Dossier où le module atterrit, relatif à la racine (en `/`, il VOYAGE). */
+		moduleDir: layout.createDir,
+		/**
+		* Version de départ. Un paquet d'un monorepo suit la version de SA racine
+		* (verrouillage naturel : tous les paquets du dépôt avancent ensemble) ; un
+		* module local d'application démarre à `0.1.0`, il a sa propre vie.
+		*/
+		version: layout.kind === "packages" ? appManifest.version ?? "0.1.0" : "0.1.0"
+	};
+	const eta = new Eta(ETA_OPTIONS);
+	const templates = path.join(packageRoot, "templates", "module");
+	const tokens = {
+		__PASCAL__: pascal,
+		__KEBAB__: name
+	};
+	const written = [];
+	renderLayer(eta, path.join(templates, "base"), dest, data, written, writer, tokens);
+	if (data.service) renderLayer(eta, path.join(templates, "service"), dest, data, written, writer, tokens);
+	renderLayer(eta, path.join(templates, "ai"), dest, data, written, writer, tokens);
+	if (data.publishable) renderLayer(eta, path.join(templates, "packages"), dest, data, written, writer, tokens);
+	const notes = [];
+	if (data.command) {
+		const sub = runScaffold({
+			type: "command",
+			answers: {
+				name: "hello",
+				description: `Salue depuis le module ${name}`,
+				phase: "onReady",
+				module: pkgName,
+				service: data.service
+			},
+			dir: projectRoot,
+			force: request.force
+		}, version, { writer });
+		written.push(...sub.files);
+		notes.push(...sub.notes ?? []);
+	}
+	if (controller !== "none") {
+		const sub = runScaffold({
+			type: "controller",
+			answers: {
+				name,
+				kind: controller,
+				route: "",
+				module: pkgName
+			},
+			dir: projectRoot,
+			force: request.force
+		}, version, { writer });
+		written.push(...sub.files);
+		notes.push(...sub.notes ?? []);
+	}
+	if (frontend !== "none") {
+		const sub = runScaffold({
+			type: "front",
+			answers: {
+				name: controller === "none" ? name : `${name}-page`,
+				frontend,
+				route: `/${toKebabCase(name)}`,
+				module: pkgName
+			},
+			dir: projectRoot,
+			force: request.force
+		}, version, { writer });
+		written.push(...sub.files);
+		notes.push(...sub.notes ?? []);
+	}
+	if (!layout.workspaceDeclared && ensureWorkspaces(projectRoot, writer)) notes.push("package.json de l'app : workspaces modules/* + scripts build/typecheck/test chaînés");
+	const manifestNote = wireModuleManifest(path.join(projectRoot, "nodefony.config.ts"), pkgName, writer, layout.createDir);
+	notes.push(manifestNote ?? `nodefony.config.ts : use("${pkgName}", {}) ajouté au manifeste modules`);
+	if (!data.publishable) renderProjectAgents(eta, packageRoot, projectRoot, {
+		appName,
+		nodefonyVersion: version,
+		hasSecurity: appDeps.has("@nodefony/security"),
+		hasOrm: appDeps.has("@nodefony/orm-core"),
+		hasRealtime: appDeps.has("@nodefony/realtime"),
+		hasStudio: appDeps.has("@nodefony/studio"),
+		front: appDeps.has("@nodefony/frontend"),
+		hasMigrateRecipe: writer.exists(path.join(projectRoot, "deploy", "migrate-job.yaml")),
+		agents: [],
+		modules: listTargets(projectRoot, writer).filter((t) => t.kind === "module").map((t) => ({
+			name: t.name,
+			dir: path.relative(projectRoot, t.dir).split(path.sep).join("/")
+		}))
+	}, written, writer);
+	return {
+		dest,
+		files: written.sort(),
+		linked: [],
+		notes
+	};
+}
+/**
+* Scaffold IN-PROJECT d'un controller : résout la cible (app racine ou module),
+* rend le template de la saveur (`hello`/`rest`/`duplex`/`realtime`/`example`)
+* dans `<cible>/nodefony/controllers/` puis câble la classe dans le
+* `@controllers([...])` de l'`index.ts` cible.
+*
+* @throws hors projet, cible inconnue (le message liste les cibles), saveur
+*   realtime/duplex sans dep `@nodefony/realtime`, ou wiring impossible
+*   (actionnable).
+*/
+function runControllerScaffold(request, answers, packageRoot, writer) {
+	const projectRoot = findProjectRoot(request.dir);
+	if (!projectRoot) throw new Error("aucun projet Nodefony ici (nodefony.config.ts introuvable en remontant) — lance la commande depuis une app (créée par `nodefony create app`)");
+	const target = resolveScaffoldTarget(projectRoot, String(answers.module ?? ""), writer);
+	const kind = answers.kind;
+	const base = String(answers.name).replace(/[-_]?[Cc]ontroller$/u, "");
+	const nameClass = `${toPascalCase(base)}Controller`;
+	const kebab = toKebabCase(base);
+	const route = String(answers.route) || `/api/${kebab}`;
+	const manifest = JSON.parse(writer.read(path.join(target.dir, "package.json")));
+	const targetDeps = new Set([
+		"dependencies",
+		"devDependencies",
+		"peerDependencies"
+	].flatMap((b) => Object.keys(manifest[b] ?? {})));
+	if (!CONTROLLER_KIND_CHOICES.includes(kind)) throw new Error(`saveur « ${String(kind)} » inconnue — choix : ${CONTROLLER_KIND_CHOICES.join(" | ")}`);
+	if ((kind === "realtime" || kind === "duplex") && !targetDeps.has("@nodefony/realtime")) throw new Error(`la saveur ${kind} exige @nodefony/realtime dans ${target.name} — ajoute la dep + use("@nodefony/realtime") au manifeste, ou choisis --kind hello`);
+	const role = String(answers.role ?? "").trim();
+	if (role.length > 0 && !targetDeps.has("@nodefony/security")) throw new Error(`--role ${role} exige @nodefony/security dans ${target.name} — sans lui, @IsGranted n'est évalué par personne et la route resterait OUVERTE.\n  → l'ajouter : npm install @nodefony/security, puis use("@nodefony/security", {}) au manifeste`);
+	const eta = new Eta(ETA_OPTIONS);
+	const written = [];
+	const data = {
+		nameClass,
+		kebab,
+		route,
+		channel: kebab,
+		hasSecurity: targetDeps.has("@nodefony/security"),
+		indexPath: "",
+		helloName: kebab,
+		secureRoute: false,
+		roleGuard: role.length > 0,
+		role
+	};
+	renderLayer(eta, path.join(packageRoot, "templates", "controller", kind), target.dir, data, written, writer, {
+		__NAME__: nameClass,
+		__KEBAB__: kebab
+	});
+	wireDecoratorList(path.join(target.dir, "index.ts"), "controllers", nameClass, `./nodefony/controllers/${nameClass}`, writer);
+	written.push("index.ts");
+	const noteRole = role.length > 0 ? wireRoleHierarchy(path.join(projectRoot, "nodefony.config.ts"), role, writer) : null;
+	const NOTES = {
+		hello: [`GET  ${route}`, `WS   ${route}/echo`],
+		rest: [`REST ${route} (GET/POST) · ${route}/{id} (GET/PUT/PATCH/DELETE)`],
+		duplex: [`REST ${route} (GET/POST) · ${route}/{id} (GET/DELETE)`, `WS   ${route}/realtime (socket Nodefony — mêmes actions via socket.request/mutate)`],
+		realtime: [`WS   ${route}/realtime (socket Nodefony — canal ${kebab}:ticker, action ${kebab}:ping)`, `TEST tests/${kebab}-realtime.test.ts — \`npx vitest run\` (harnais @nodefony/realtime/testing, ni serveur ni navigateur)`],
+		example: [`REST ${route} (vitrine décorateurs — voir les curl du TSDoc généré)`, `WS   ${route}/echo`]
+	};
+	return {
+		dest: target.dir,
+		files: written.sort(),
+		linked: [],
+		notes: [...NOTES[kind], ...role.length > 0 ? [`GARDE ${role} sur TOUT le controller (@IsGranted de classe) — ` + (noteRole === null ? `déclaré sous ROLE_ADMIN dans roleHierarchy : l'administrateur y a accès sans porter ce rôle` : `⚠ hiérarchie NON modifiée — ${noteRole}`)] : []]
+	};
+}
+/**
+* Scaffold IN-PROJECT d'un service injectable : résout la cible (app racine ou
+* module), rend la classe (`@injectable`, `extends Service`) + son interface
+* dans `<cible>/nodefony/{service,interfaces}/`, puis câble la classe dans le
+* `@services([...])` de l'`index.ts` cible — CRÉÉ s'il n'existe pas encore
+* (cf {@link wireDecoratorList}, seul cas où l'absence du décorateur n'est pas
+* un refus).
+*
+* Volontairement AUTONOME : contrairement au service PRINCIPAL d'un module
+* (`create module`, gabarit `templates/module/service/`), celui-ci ne dépend
+* d'aucun `nodefony/config/config.ts` — une cible existante (app racine, ou
+* module créé avec `--no-service`) n'en a pas forcément un, et le résultat
+* doit compiler tel quel, sans édition manuelle.
+*
+* @throws hors projet, cible inconnue (le message liste les cibles), ou nom
+*   déjà référencé dans l'`index.ts` cible.
+*/
+function runServiceScaffold(request, answers, packageRoot, writer) {
+	const projectRoot = findProjectRoot(request.dir);
+	if (!projectRoot) throw new Error("aucun projet Nodefony ici (nodefony.config.ts introuvable en remontant) — lance la commande depuis une app (créée par `nodefony create app`)");
+	const target = resolveScaffoldTarget(projectRoot, String(answers.module ?? ""), writer);
+	const base = String(answers.name).replace(/[-_]?[Ss]ervice$/u, "");
+	const pascal = toPascalCase(base);
+	const nameClass = `${pascal}Service`;
+	const camel = pascal[0].toLowerCase() + pascal.slice(1);
+	const existing = listTargetServices(target.dir, writer);
+	const injectName = String(answers.inject ?? "").trim();
+	let inject = null;
+	if (injectName !== "") {
+		const wanted = `${toPascalCase(injectName.replace(/[-_]?[Ss]ervice$/u, ""))}Service`;
+		const found = existing.find((s) => s.pascal === wanted);
+		if (!found) {
+			const known = existing.map((s) => s.pascal).join(" · ") || "aucun";
+			throw new Error(`--inject : « ${injectName} » introuvable dans ${target.name} (services de la cible : ${known}) — crée-le d'abord, ou relance sans --inject`);
+		}
+		if (found.pascal === nameClass) throw new Error(`--inject : un service ne s'injecte pas lui-même (${nameClass})`);
+		const method = findCallableMethod(found.source);
+		if (method === null) throw new Error(`--inject : ${found.pascal} n'expose aucune méthode publique appelable sans argument obligatoire — le service injecté serait déclaré sans être appelé`);
+		inject = {
+			pascal: found.pascal,
+			key: found.key,
+			camel: found.key[0].toLowerCase() + found.key.slice(1),
+			method
+		};
+	}
+	const eta = new Eta(ETA_OPTIONS);
+	const written = [];
+	renderLayer(eta, path.join(packageRoot, "templates", "service"), target.dir, {
+		pascal,
+		camel,
+		inject,
+		description: String(answers.description) || `Service ${pascal} de ${target.name}`
+	}, written, writer, { __PASCAL__: pascal });
+	wireDecoratorList(path.join(target.dir, "index.ts"), "services", nameClass, `./nodefony/service/${nameClass}`, writer);
+	written.push("index.ts");
+	const notes = [`DI   container.get("${camel}")  — clé du conteneur (super("${camel}", …))`, `DI   @inject("${nameClass}")    — nom de classe (@injectable)`];
+	if (inject) notes.push(`DI   ${inject.pascal} est injecté par le CONSTRUCTEUR — dépendance déclarée, ordonnée par le conteneur`);
+	else if (existing.length > 0) notes.push(`DI   pour appeler ${existing[0].pascal} depuis ce service, injecte-le : nodefony create service ${base} --inject ${existing[0].pascal}`);
+	return {
+		dest: target.dir,
+		files: written.sort(),
+		linked: [],
+		notes
+	};
+}
+/**
+* Retire commentaires de bloc et de ligne d'une source TypeScript.
+*
+* ⚠️ Approximation assumée — une chaîne contenant `//` (une URL) perd sa fin.
+* C'est sans effet ici : les lecteurs ci-dessous cherchent une FORME de code
+* (`super("…"`, une signature de méthode), jamais le contenu d'une chaîne.
+* L'inverse, lui, s'est produit : un TSDoc qui CITE `super("autreService", …)`
+* pour expliquer la clé d'un voisin faisait lire cette clé-là. Un fichier bien
+* documenté est le cas NORMAL, pas le cas tordu.
+*
+* @param source - le contenu du fichier.
+* @returns la même source, commentaires blanchis.
+*/
+function stripComments(source) {
+	return source.replace(/\/\*[\s\S]*?\*\//gu, "").replace(/(^|[^:])\/\/[^\n]*/gu, "$1");
+}
+/**
+* Nom Nodefony déclaré par le premier `super("…", …)` d'un fichier — celui d'un
+* `Module` (`index.ts`) ou d'un `Service`.
+*
+* C'est la CLÉ du conteneur, et pour un module le préfixe de ses commandes CLI
+* (`<module>:<action>`). Elle ne se déduit ni du nom npm du paquet ni du nom de
+* la classe : les trois peuvent différer, et seule celle-ci existe au runtime.
+*
+* Lue sur le CODE seul : un `super("…")` cité dans un TSDoc pour documenter un
+* autre service faisait rendre la clé du voisin — la commande générée importait
+* alors une classe et résolvait l'instance d'une autre.
+*
+* @returns le nom déclaré, ou `null` si le fichier ne suit pas la forme attendue.
+*/
+function readNodefonyName(file, writer) {
+	try {
+		return /\bsuper\(\s*"([^"]+)"/u.exec(stripComments(writer.read(file)))?.[1] ?? null;
+	} catch {
+		return null;
+	}
+}
+/**
+* Première méthode d'un service qu'une commande peut appeler SANS argument.
+*
+* On cherche une méthode **publique** dont tous les paramètres sont facultatifs
+* (aucun, ou tous avec `?`/valeur par défaut) : c'est la seule forme dont on
+* puisse produire un appel qui compile à coup sûr. Le cycle de vie (`init`) et
+* le constructeur sont exclus — les appeler serait un contresens.
+*
+* ⚠️ Analyse TEXTUELLE, volontairement conservatrice : à la moindre signature
+* qu'on ne sait pas lire, on passe. Mieux vaut refuser `--service` que livrer un
+* appel qui ne compile pas.
+*
+* @returns le nom de la méthode, ou `null` si aucune ne convient.
+*/
+function findCallableMethod(source) {
+	for (const m of source.matchAll(/^ {2}(?:public\s+)?(?:async\s+)?([a-z][A-Za-z0-9_]*)\s*\(([^)]*)\)/gmu)) {
+		const [, name, params] = m;
+		if (name === "constructor" || name === "init" || name === "if") continue;
+		const args = params.trim();
+		if (args === "" || args.split(",").every((p) => p.includes("=") || /\?\s*:/u.test(p) || p.trim() === "")) return name;
+	}
+	return null;
+}
+/**
+* Les services d'une cible : classe, clé de conteneur, source.
+*
+* Point UNIQUE qui sait où vivent les services et comment on les nomme —
+* `--service` de `create command` et `--inject` de `create service` en
+* dépendent tous deux. Deux façons de « trouver les services » divergeraient en
+* silence, chacune passant ses propres essais.
+*
+* Un fichier dont on ne sait pas lire le `super("…", …)` est ignoré : sans clé
+* de conteneur, il n'est atteignable par personne, donc il n'est pas un
+* candidat.
+*/
+function listTargetServices(targetDir, writer) {
+	const dir = path.join(targetDir, "nodefony", "service");
+	if (!writer.exists(dir)) return [];
+	const found = [];
+	for (const entry of writer.listDir(dir)) {
+		if (entry.isDirectory || !entry.name.endsWith("Service.ts")) continue;
+		const file = path.join(dir, entry.name);
+		const key = readNodefonyName(file, writer);
+		if (key === null) continue;
+		found.push({
+			pascal: entry.name.replace(/\.ts$/u, ""),
+			key,
+			source: writer.read(file)
+		});
+	}
+	return found;
+}
+/**
+* Service appelable de la cible : sa classe, sa clé de conteneur, sa méthode.
+*
+* ⚠️ La méthode est CHERCHÉE, pas supposée. Elle a longtemps été exigée par son
+* nom (`greet`, celui du gabarit) — or ce même gabarit dit « à remplacer par la
+* vôtre » : suivre le conseil cassait `--service`, sur un message qui réclamait
+* une méthode d'exemple. Un générateur ne doit pas exiger que son propre exemple
+* soit resté intact.
+*
+* ⚠️ **Le premier venu n'est une réponse que s'il est le SEUL.** Sans `wanted`,
+* cette fonction rendait le premier service de l'ordre du disque — donc le
+* premier alphabétiquement. Tant qu'une application n'avait qu'un service
+* d'exemple, le hasard tombait juste ; dès le deuxième, la commande générée
+* appelait un service que personne n'avait demandé, et rien ne le disait. Une
+* application réelle en a dix.
+*
+* @param targetDir - racine de la cible (app ou module).
+* @param writer - accès disque injecté.
+* @param wanted - nom du service voulu : classe (`ReportService`, `Report`) ou
+*   clé de conteneur (`report`). Omis, la cible ne doit en avoir qu'un.
+* @returns `{ pascal, key, method }`, ou `null` si la cible n'a aucun service
+*   dont une méthode soit appelable sans argument.
+* @throws Si `wanted` ne correspond à rien, ou si plusieurs services sont
+*   appelables et qu'aucun n'est désigné — dans les deux cas en NOMMANT les
+*   candidats : refuser en donnant le choix coûte un essai, produire un appel
+*   vers le mauvais service coûte un débogage.
+*/
+function findTargetService(targetDir, writer, wanted) {
+	const callables = [];
+	for (const { pascal, key, source } of listTargetServices(targetDir, writer)) {
+		const method = findCallableMethod(source);
+		if (method !== null) callables.push({
+			pascal,
+			key,
+			method
+		});
+	}
+	if (callables.length === 0) return null;
+	const names = callables.map((s) => `${s.pascal} (clé « ${s.key} »)`).join(", ");
+	if (wanted !== void 0) {
+		const needle = wanted.toLowerCase().replace(/service$/u, "");
+		const found = callables.find((s) => s.pascal.toLowerCase().replace(/service$/u, "") === needle || s.key.toLowerCase() === wanted.toLowerCase());
+		if (found === void 0) throw new Error(`--service ${wanted} : aucun service de ce nom dans ${targetDir} — services appelables : ${names}`);
+		return found;
+	}
+	if (callables.length > 1) throw new Error(`--service : ${callables.length} services appelables, précise lequel (--service <Nom>) — ${names}`);
+	return callables[0];
+}
+/**
+* Câble `this.addCommand(<Classe>)` dans le constructeur du Module d'un
+* `index.ts` : ajoute l'import après le dernier import, insère l'appel juste
+* après le `super(…)` du constructeur.
+*
+* L'ancre est le `super(…)` et non l'accolade du constructeur : c'est la seule
+* ligne dont l'existence est GARANTIE (un `Module` doit appeler `super`), et
+* insérer après elle vaut pour un constructeur vide comme pour un constructeur
+* déjà rempli. Édition textuelle gardée, même contrat que
+* {@link wireDecoratorList} : toute ambiguïté = throw actionnable, jamais un
+* fichier corrompu.
+*
+* @throws si la classe y est déjà, si aucun import n'ancre l'insertion, ou si
+*   le `super(…)` du constructeur est introuvable (le message donne l'édition
+*   manuelle exacte).
+*/
+function wireCommandCall(indexPath, className, importPath, writer) {
+	const source = writer.read(indexPath);
+	const importLine = `import ${className} from "${importPath}";`;
+	const callLine = `this.addCommand(${className});`;
+	if (new RegExp(`\\b${className}\\b`, "u").test(source)) throw new Error(`${className} est déjà référencé dans ${indexPath} — choisis un autre nom`);
+	const last = [...source.matchAll(/^import [^\n]*$/gmu)].at(-1);
+	if (!last || last.index === void 0) throw new Error(`aucun import trouvé dans ${indexPath} — ajoute à la main :\n  ${importLine}\n  ${callLine} dans le constructeur`);
+	const importAt = last.index + last[0].length;
+	const withImport = source.slice(0, importAt) + `\n${importLine}` + source.slice(importAt);
+	const match = /super\([^()]*\);/u.exec(withImport);
+	if (!match || match.index === void 0) throw new Error(`super(…) du constructeur introuvable dans ${indexPath} — ajoute à la main :\n  ${importLine}\n  ${callLine} après le super(…) du constructeur`);
+	const lineStart = withImport.lastIndexOf("\n", match.index) + 1;
+	const indent = /^[ \t]*/u.exec(withImport.slice(lineStart, match.index))?.[0] ?? "    ";
+	const at = match.index + match[0].length;
+	writer.write(indexPath, `${withImport.slice(0, at)}\n${indent}${callLine}${withImport.slice(at)}`);
+}
+/**
+* Scaffold IN-PROJECT d'une commande CLI : rend la classe dans
+* `<cible>/nodefony/command/` puis la câble dans le constructeur du Module
+* cible (`this.addCommand(…)`).
+*
+* Le nom complet est DÉRIVÉ : `<module>:<action>`, où le module est celui que
+* l'`index.ts` de la cible déclare (`super("blog", …)`) — pas le nom npm du
+* paquet, qui peut différer. Écrire le préfixe soi-même est toléré (il est
+* strippé), jamais exigé.
+*
+* @throws hors projet, cible inconnue (le message liste les cibles), action
+*   vide, phase inconnue, `--service` sans service appelable, ou wiring
+*   impossible (actionnable).
+*/
+function runCommandScaffold(request, answers, packageRoot, writer) {
+	const projectRoot = findProjectRoot(request.dir);
+	if (!projectRoot) throw new Error("aucun projet Nodefony ici (nodefony.config.ts introuvable en remontant) — lance la commande depuis une app (créée par `nodefony create app`)");
+	const moduleName = String(answers.module ?? "");
+	const target = resolveScaffoldTarget(projectRoot, moduleName, writer);
+	const indexPath = path.join(target.dir, "index.ts");
+	const prefix = readNodefonyName(indexPath, writer) ?? target.name.split("/").pop();
+	let action = String(answers.name).trim().toLowerCase();
+	if (action === prefix) action = "";
+	else if (action.startsWith(`${prefix}:`)) action = action.slice(prefix.length + 1);
+	if (action === "") throw new Error(`action requise (le préfixe « ${prefix} » est ajouté seul) — ex : nodefony create command publish${moduleName ? ` --module ${moduleName}` : ""}`);
+	const phase = String(answers.phase);
+	const commandName = `${prefix}:${action}`;
+	const nameClass = `${toPascalCase(action.replaceAll(":", "-"))}Command`;
+	const serviceName = String(answers.serviceName ?? "").trim();
+	const service = answers.service === true ? findTargetService(target.dir, writer, serviceName === "" ? void 0 : serviceName) : null;
+	if (answers.service === true && service === null) throw new Error(`--service : aucun service appelable dans ${target.name} (attendu : nodefony/service/*Service.ts exposant une méthode publique sans argument obligatoire) — relance sans --service`);
+	const eta = new Eta(ETA_OPTIONS);
+	const written = [];
+	renderLayer(eta, path.join(packageRoot, "templates", "command"), target.dir, {
+		nameClass,
+		commandName,
+		phase,
+		description: String(answers.description) || `Commande ${commandName} de ${prefix}`,
+		service
+	}, written, writer, { __NAME__: nameClass });
+	wireCommandCall(indexPath, nameClass, `./nodefony/command/${nameClass}`, writer);
+	written.push("index.ts");
+	return {
+		dest: target.dir,
+		files: written.sort(),
+		linked: [],
+		notes: [`CLI  nodefony ${commandName} [who] [-j]  (phase ${phase})`, `visible dans \`nodefony --help\` une fois le module construit`]
+	};
+}
+/**
+* Valeur d'exemple d'un champ — VALIDE au regard du schéma de l'entité.
+*
+* Un échantillon n'est pas une décoration : les tests générés s'en servent pour
+* insérer, et la documentation pour montrer un appel qui marche. S'il viole le
+* schéma, l'entité naît avec un test rouge, et la première impression du
+* générateur est qu'il produit du code cassé.
+*
+* Ce piège s'est présenté trois fois, sur trois types ajoutés à trois moments
+* différents — l'énumération, puis le décimal et le caractère fixe. Chaque fois,
+* la valeur générique `nom-1` passait à côté d'une contrainte que le schéma, lui,
+* faisait respecter. D'où cette fonction unique : tout type qui restreint ses
+* valeurs doit dire ici ce qu'il accepte, sinon rien ne le rappellera.
+*
+* @param field - le champ à illustrer.
+* @param id - stratégie de clé primaire (une référence vers une clé numérique
+*   attend un nombre, pas une chaîne).
+* @returns `fixed` pour le JSON de la documentation, `expr` pour la fabrique
+*   paramétrée des tests (une expression TypeScript où `n` varie).
+*/
+/**
+* Le filtre sur lequel le test généré peut prouver qu'un filtre FILTRE — ou
+* `null` si aucun champ ne s'y prête.
+*
+* Prouver un refus (`?actf=x` → 400) et prouver un filtre sont deux choses
+* différentes, et la seconde exige une ligne qui NE matche PAS. Sans elle,
+* l'assertion « toutes les lignes rendues portent la valeur demandée » reste
+* vraie quand le filtre est ignoré : tous les échantillons d'un booléen valent
+* `true`, ceux d'une énumération valent sa première valeur ({@link sampleValue}).
+* Le test serait vert sur un filtre débranché — exactement le défaut qu'il est
+* censé attraper.
+*
+* D'où les deux seules natures retenues, celles qui offrent un contraire sûr et
+* gratuit. Une clé étrangère en est écartée : poser une seconde valeur
+* demanderait de créer l'entité visée, et le test parlerait d'autre chose.
+*
+* Deux écritures de chaque valeur, et ce n'est pas une redondance : `match` part
+* dans l'URL (`?publie=true` — tout y est du texte), `matchJson` est la
+* littérale TypeScript posée dans le corps envoyé (`publie: true`, un booléen —
+* `"true"` y serait refusé par le schéma).
+*
+* @param fields - les champs déclarés de l'entité.
+* @returns le nom du filtre et ses deux valeurs sous les deux écritures, ou
+*   `null` si l'entité n'a aucun champ éprouvable.
+*/
+function filterProbe(fields) {
+	for (const f of fields) {
+		if (f.nullable) continue;
+		if (f.type === "bool") return {
+			name: f.name,
+			match: "true",
+			matchJson: "true",
+			other: "false",
+			otherJson: "false"
+		};
+		if (f.type === "enum" && (f.values?.length ?? 0) >= 2) {
+			const [a, b] = f.values;
+			return {
+				name: f.name,
+				match: a,
+				matchJson: JSON.stringify(a),
+				other: b,
+				otherJson: JSON.stringify(b)
+			};
+		}
+	}
+	return null;
+}
+/**
+* Le filtre sur lequel une valeur MAL FORMÉE existe, et de quoi la fabriquer —
+* ou `null` si aucun filtre de l'entité ne peut en refuser une.
+*
+* Toutes les natures ne refusent pas : un filtre `"string"` accepte n'importe
+* quelle chaîne, par construction. Le test généré visait pourtant le PREMIER
+* filtre déclaré quel qu'il soit, et attendait un `400` — sur une entité dont
+* le seul filtre est une clé étrangère à identifiant textuel
+* (`author:ref:Author` avec des `uuid`), il exigeait donc le refus d'une valeur
+* parfaitement valide, et échouait sur le générateur au lieu de l'éprouver.
+*
+* @param filters - le vocabulaire de filtre déjà calculé (nom → littérale de sa
+*   nature, telle qu'elle sera écrite dans le gabarit).
+* @returns le nom du filtre et une valeur qu'il doit refuser, ou `null`.
+*/
+function malformedProbe(filters) {
+	for (const f of filters) {
+		if (f.def === "\"boolean\"") return {
+			name: f.name,
+			value: "oui"
+		};
+		if (f.def === "\"int\"") return {
+			name: f.name,
+			value: "abc"
+		};
+		if (f.def.startsWith("[")) return {
+			name: f.name,
+			value: "valeur-hors-domaine"
+		};
+	}
+	return null;
+}
+function sampleValue(field, id) {
+	const { name, type } = field;
+	if (type === "int" || type === "float") return {
+		fixed: 1,
+		expr: "n"
+	};
+	if (type === "bool") return {
+		fixed: true,
+		expr: "true"
+	};
+	if (type === "json") return {
+		fixed: {},
+		expr: "{}"
+	};
+	if (type === "date") return {
+		fixed: "2026-01-01T00:00:00.000Z",
+		expr: "new Date()"
+	};
+	if (type === "enum") {
+		const value = field.defaultValue ?? field.values?.[0] ?? "";
+		return {
+			fixed: value,
+			expr: JSON.stringify(value)
+		};
+	}
+	const echantillonUuid = () => ({
+		fixed: `00000000-0000-4000-8000-${"1".padStart(12, "0")}`,
+		expr: `\`00000000-0000-4000-8000-\${String(n).padStart(12, "0")}\``
+	});
+	if (type === "ref") return id === "serial" ? {
+		fixed: 1,
+		expr: "n"
+	} : echantillonUuid();
+	if (type === "uuid") return echantillonUuid();
+	if (type === "decimal") return {
+		fixed: "12.34",
+		expr: "`${n}.50`"
+	};
+	if (type === "char") {
+		const size = field.length ?? 1;
+		return {
+			fixed: "A".repeat(size),
+			expr: `String(n).padStart(${size}, "A").slice(-${size})`
+		};
+	}
+	const max = field.length;
+	if (type === "string" && max !== void 0) return {
+		fixed: `${name}-1`.slice(0, max),
+		expr: `\`${name}-\${n}\`.slice(0, ${max})`
+	};
+	return {
+		fixed: `${name}-1`,
+		expr: `\`${name}-\${n}\``
+	};
+}
+/** Pluriel simple, suffisant pour un nom de table (`Post` → `posts`, `Story` → `stories`). */
+function pluralize(word) {
+	if (/[^aeiou]y$/u.test(word)) return `${word.slice(0, -1)}ies`;
+	if (/(s|x|z|ch|sh)$/u.test(word)) return `${word}es`;
+	return `${word}s`;
+}
+/**
+* `BlogPost` → `blog_posts` — nom de table SQL par DÉFAUT.
+*
+* Par défaut seulement : `--table` impose un nom littéral, seul moyen d'épouser une
+* table qui existe déjà (`website`, `session`) — la pluralisation ne se devine pas à
+* l'envers, et une table réelle ne demande la permission à personne.
+*
+* La casse vient de {@link toSnakeCase}, la même que celle des colonnes : deux
+* grammaires auraient fini par diverger sur un nom composé.
+*/
+function tableName(pascal) {
+	return pluralize(toSnakeCase(pascal));
+}
+/**
+* Identifiant SQL acceptable — minuscules, chiffres, tiret bas.
+*
+* Volontairement plus strict que ce que les moteurs tolèrent entre guillemets : un
+* nom qui exige d'être cité voyage mal d'un dialecte à l'autre, et le générateur
+* l'écrirait sans les guillemets qui le sauvent.
+*/
+const SQL_NAME_RE = /^[a-z_][a-z0-9_]*$/u;
+/** Refuse un identifiant SQL AVANT toute écriture, en nommant ce qui est attendu. */
+function assertSqlName(value, option) {
+	if (!SQL_NAME_RE.test(value)) throw new Error(`${option} invalide « ${value} » — un identifiant SQL commence par une lettre minuscule ou « _ », puis minuscules, chiffres et « _ » (ex : website_id)`);
+	return value;
+}
+/**
+* Dialecte SQL du connecteur visé — **l'infra déclarée d'abord**, le fichier ensuite.
+*
+* L'ordre n'est pas un détail de confort : c'est celui du RUNTIME. Une
+* application déclare sa base par URL (`NF_DATABASE_URL`, modèle « infra
+* déclarée » — docker, conteneur, CI, production), et `nodefony.config.ts` ne
+* porte alors aucun dialecte. Le scaffold, qui ne lisait que le fichier,
+* retombait sur `sqlite` et générait du Drizzle SQLite pour une application qui
+* tourne sur PostgreSQL. Le DDL de développement créait ensuite les colonnes
+* telles quelles : chaînes bornées devenues `text`, identifiants `uuid` devenus
+* `text` — et là c'est structurel, PostgreSQL refuse `text = uuid`, donc toute
+* jointure écrite ensuite échoue.
+*
+* Mesuré sur un schéma réel (banc de schéma, umami) : **18 identifiants
+* dégradés et 32 longueurs perdues** sur 83 colonnes, sans un mot.
+*
+* La déduction depuis l'URL n'est pas réécrite ici : {@link resolveInfra} en est
+* la source unique, la même que celle qu'exécute le kernel. Un scaffold qui
+* dériverait son propre scheme divergerait au premier alias ajouté.
+*
+* Le fichier reste consulté ensuite : un connecteur qui déclare explicitement
+* son dialecte l'emporte sur un défaut, et une app multi-connecteurs n'a pas
+* qu'une base.
+*/
+function detectDialect(projectRoot, writer, connector = "default") {
+	const connectors = readConnectors(projectRoot, writer);
+	const found = connectors.find((c) => c.name === connector);
+	if (found && declaresDialect(projectRoot, writer, connector)) return found.dialect;
+	const declared = infraDialect(projectRoot);
+	if (declared) return declared;
+	if (found) return found.dialect;
+	return connectors[0]?.dialect ?? "sqlite";
+}
+/**
+* Le dialecte du connecteur est-il ÉCRIT dans `nodefony.config.ts` ?
+*
+* {@link readConnectors} ne peut pas répondre : il rend `sqlite` aussi bien pour
+* un `dialect: "sqlite"` assumé que pour une absence de déclaration. Distinguer
+* les deux est tout l'enjeu — sans cela, l'infra déclarée ne pourrait jamais
+* s'appliquer, puisqu'un défaut lui ressemblerait toujours à un choix.
+*/
+function declaresDialect(projectRoot, writer, connector) {
+	const configPath = path.join(projectRoot, "nodefony.config.ts");
+	if (!writer.exists(configPath)) return false;
+	const block = extractBlock(writer.read(configPath), "connectors");
+	if (block === null) return false;
+	const entry = /(\w+)\s*:\s*\{([^{}]*)\}/gu;
+	let match;
+	while ((match = entry.exec(block)) !== null) {
+		if (match[1] !== connector) continue;
+		return /dialect\s*:\s*["'](\w+)["']/u.test(match[2] ?? "");
+	}
+	return false;
+}
+/**
+* Dialecte de l'infra DÉCLARÉE du projet, cascade `.env` comprise.
+*
+* `process.env` seul ne suffit pas : une URL posée dans `.env.local` (le cas
+* nominal en développement — le fichier est gitignoré, c'est là qu'on met sa
+* base) n'est pas dans l'environnement du terminal qui lance le scaffold. On
+* emprunte donc l'ORDRE de la cascade au runtime ({@link envFileOrder}) plutôt
+* que d'en inventer un : un ordre affiché qui différerait de l'ordre appliqué
+* serait pire que pas d'ordre du tout.
+*
+* @returns le dialecte SQL, ou `null` si aucune base n'est déclarée (ou si elle
+*   n'est pas SQL — une base mongo ne dicte aucun dialecte à `create entity`).
+*/
+function infraDialect(projectRoot) {
+	const env = {};
+	try {
+		for (const name of envFileOrder()) {
+			const file = path.join(projectRoot, name);
+			if (!existsSync(file)) continue;
+			for (const line of readFileSync(file, "utf8").split("\n")) {
+				const m = /^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)$/u.exec(line);
+				if (!m?.[1]) continue;
+				if (env[m[1]] === void 0) env[m[1]] = m[2]?.trim().replace(/^["']|["']$/gu, "");
+			}
+		}
+	} catch {}
+	try {
+		const dialect = resolveInfra({
+			...env,
+			...process.env
+		}).database?.dialect;
+		return dialect && ENTITY_DIALECTS.includes(dialect) ? dialect : null;
+	} catch {
+		return null;
+	}
+}
+/**
+* Contenu de l'objet qui suit `<clé>:`, borné par son accolade APPARIÉE.
+*
+* Sans appariement, une expression régulière lâche continue de trouver des
+* entrées bien après la fin du bloc visé — elle ramasserait alors tout le reste
+* du fichier de configuration.
+*
+* @returns le corps du bloc (accolades exclues), ou `null` si la clé est absente.
+*/
+function extractBlock(source, key) {
+	const at = source.indexOf(key);
+	if (at < 0) return null;
+	const open = source.indexOf("{", at);
+	if (open < 0) return null;
+	let depth = 0;
+	for (let i = open; i < source.length; i += 1) if (source[i] === "{") depth += 1;
+	else if (source[i] === "}") {
+		depth -= 1;
+		if (depth === 0) return source.slice(open + 1, i);
+	}
+	return null;
+}
+/**
+* Connecteurs déclarés par l'application, lus SANS démarrer le noyau.
+*
+* Lecture TEXTUELLE assumée : `nodefony.config.ts` est du TypeScript, et
+* l'exécuter pour lire une clé coûterait un boot complet. On isole donc le bloc
+* `connectors: { … }` puis chaque entrée `<nom>: { … dialect: "…" }`.
+*
+* Pourquoi ne pas se contenter de chercher le premier `dialect:` du fichier :
+* une application qui déclare deux connecteurs de moteurs différents ferait
+* générer TOUTES ses entités dans le dialecte du premier, sans un mot.
+*
+* @param projectRoot - racine du projet (là où vit `nodefony.config.ts`).
+* @param writer - accès fichiers transactionnel du scaffold.
+* @returns les connecteurs trouvés, dans l'ordre de déclaration (vide si aucun).
+*/
+function readConnectors(projectRoot, writer) {
+	const configPath = path.join(projectRoot, "nodefony.config.ts");
+	if (!writer.exists(configPath)) return [];
+	const source = writer.read(configPath);
+	const asDialect = (value) => ENTITY_DIALECTS.includes(value ?? "") ? value : "sqlite";
+	const connectors = [];
+	const block = extractBlock(source, "connectors");
+	if (block !== null) {
+		const entry = /(\w+)\s*:\s*\{([^{}]*)\}/gu;
+		let match;
+		while ((match = entry.exec(block)) !== null) {
+			const [, name, body] = match;
+			if (!name) continue;
+			const ddl = /ddl\s*:\s*["'](\w+)["']/u.exec(body ?? "")?.[1];
+			connectors.push({
+				name,
+				dialect: asDialect(/dialect\s*:\s*["'](\w+)["']/u.exec(body ?? "")?.[1]),
+				...ddl !== void 0 ? { ddl } : {}
+			});
+		}
+	}
+	if (connectors.length > 0) return connectors;
+	return [{
+		name: "default",
+		dialect: asDialect(/dialect\s*:\s*["'](\w+)["']/u.exec(source)?.[1])
+	}];
+}
+/**
+* Entités déjà déclarées dans une cible, lues au disque.
+*
+* Sert à transformer `ref:` d'un texte libre en un CHOIX : le formulaire de
+* Studio comme le dialogue du terminal peuvent proposer ce qui existe vraiment,
+* au lieu de laisser deviner un nom qui fera échouer le démarrage.
+*/
+function readEntities(targetDir, writer) {
+	const dir = path.join(targetDir, "nodefony", "entity");
+	if (!writer.exists(dir)) return [];
+	return writer.listDir(dir).filter((file) => !file.isDirectory && file.name.endsWith(".ts") && !file.name.endsWith(".schema.ts")).map((file) => file.name.slice(0, -3)).sort();
+}
+/**
+* Scaffold IN-PROJECT d'une entité (`create entity`) : table Drizzle native, interface
+* de ligne, schémas Zod d'entrée, service CRUD, controller REST + WebSocket, tests.
+*
+* Câble la cible : `@entities([...])` (créé au besoin) et `@controllers([...])`.
+*
+* @throws hors projet · cible inconnue · aucun module ORM dans les dépendances ·
+*   entité déjà déclarée · champ mal formé.
+*/
+function runEntityScaffold(request, answers, packageRoot, writer) {
+	const projectRoot = findProjectRoot(request.dir);
+	if (!projectRoot) throw new Error("aucun projet Nodefony ici (nodefony.config.ts introuvable en remontant) — lance la commande depuis une app (créée par `nodefony create app`)");
+	const target = resolveScaffoldTarget(projectRoot, String(answers.module ?? ""), writer);
+	const manifestPath = path.join(target.dir, "package.json");
+	const manifest = JSON.parse(writer.read(manifestPath));
+	const depsOf = (dir) => {
+		const file = path.join(dir, "package.json");
+		if (!writer.exists(file)) return /* @__PURE__ */ new Set();
+		const pkg = JSON.parse(writer.read(file));
+		return new Set([
+			"dependencies",
+			"devDependencies",
+			"peerDependencies"
+		].flatMap((b) => Object.keys(pkg[b] ?? {})));
+	};
+	const targetDeps = depsOf(target.dir);
+	const projectDeps = depsOf(projectRoot);
+	if (!targetDeps.has("@nodefony/drizzle") && !projectDeps.has("@nodefony/drizzle")) throw new Error(`@nodefony/drizzle absent de ${target.name} — ajoute la dep + use("@nodefony/drizzle") au manifeste modules de nodefony.config.ts, puis relance`);
+	const ormRuntimeNote = [];
+	const depsAdded = [];
+	{
+		const rootManifestPath = path.join(projectRoot, "package.json");
+		let rootManifest = null;
+		const ensure = (section, dep, why) => {
+			if (projectDeps.has(dep)) return;
+			rootManifest ??= JSON.parse(writer.read(rootManifestPath));
+			rootManifest[section] ??= {};
+			rootManifest[section][dep] = SCAFFOLD_VERSIONS[dep];
+			depsAdded.push(dep);
+			ormRuntimeNote.push(`dépendance manquante ajoutée au package.json : ${dep}@${SCAFFOLD_VERSIONS[dep]} (${why})`);
+		};
+		ensure("dependencies", "drizzle-orm", "l'entité l'importe en direct");
+		ensure("devDependencies", "drizzle-kit", "`nodefony orm:generate` le pilote pour écrire les migrations");
+		if (rootManifest !== null) writer.write(rootManifestPath, `${JSON.stringify(rootManifest, null, 2)}\n`);
+	}
+	const base = String(answers.name).replace(/[-_]?[Ee]ntity$/u, "");
+	const pascal = toPascalCase(base);
+	const reserved = findReservedEntity(pascal);
+	if (reserved && !reserved.appOwned) throw new Error(`create entity ${pascal} : ce nom appartient au module « ${reserved.module} » (entité « ${reserved.name} ») — deux entités du même nom ne cohabitent pas dans le registre ORM, et l'application ne démarrerait plus.\n  → ${reserved.advice}`);
+	const isUserEntity = reserved?.appOwned === true;
+	if (isUserEntity && target.kind !== "app") throw new Error(`create entity ${pascal} : l'entité de l'utilisateur ne peut vivre que dans l'application RACINE, pas dans le module « ${target.name} ». L'ordre de chargement des modules n'est pas garanti : posée ailleurs, elle arriverait parfois APRÈS celle du framework, et le registre d'entités refuserait le doublon par une exception au démarrage.\n  → relancer sans « --module »`);
+	if (isUserEntity) {
+		const refuse = (option, value, impose) => {
+			throw new Error(`create entity ${pascal} : « ${option} ${value} » est refusé — ${impose}. Le framework écrit ces noms en dur dans ses requêtes (recherche par compte externe, listing) : une divergence ne lèverait pas, elle rendrait simplement des résultats vides.\n  → relancer sans « ${option} »`);
+		};
+		if (String(answers.table ?? "").trim()) refuse("--table", String(answers.table), "la table s'appelle « User »");
+		if (answers.columnCase !== void 0 && answers.columnCase !== "camel") refuse("--column-case", String(answers.columnCase), "les colonnes du contrat sont en camelCase");
+		if (String(answers.id) === "serial") refuse("--id", String(answers.id), "l'identifiant de l'utilisateur est un UUID (un entier auto-incrémenté est devinable, donc énumérable)");
+		if (answers.idName !== void 0 && String(answers.idName) !== "id") refuse("--id-name", String(answers.idName), "la clé primaire s'appelle « id »");
+	}
+	const camel = pascal.charAt(0).toLowerCase() + pascal.slice(1);
+	const kebab = toKebabCase(base);
+	const tableAnswer = String(answers.table ?? "").trim();
+	const table = isUserEntity ? userTableName(target.dir) : tableAnswer ? assertSqlName(tableAnswer, "--table") : tableName(pascal);
+	const columnCase = String(answers.columnCase ?? "camel");
+	if (!COLUMN_CASES.includes(columnCase)) throw new Error(`--column-case invalide « ${columnCase} » — attendus : ${COLUMN_CASES.join(" | ")}`);
+	const idName = assertSqlName(String(answers.idName ?? "id").trim() || "id", "--id-name");
+	const connector = String(answers.connector || "default");
+	const dialect = String(answers.dialect || "") || detectDialect(projectRoot, writer, connector);
+	if (!ENTITY_DIALECTS.includes(dialect)) throw new Error(`dialecte invalide « ${dialect} » — attendus : ${ENTITY_DIALECTS.join(" | ")}`);
+	const id = String(answers.id);
+	if (!ENTITY_ID_KINDS.includes(id)) throw new Error(`--id invalide « ${id} » — attendus : ${ENTITY_ID_KINDS.join(" | ")}`);
+	const requested = parseEntityFields(String(answers.fields ?? ""));
+	const contract = isUserEntity ? readUserContract(target.dir) : null;
+	if (isUserEntity) assertUserFieldsAreFillable(requested);
+	const fields = contract ? [...userContractFields(contract), ...requested] : requested;
+	if (fields.length === 0) throw new Error(`create entity ${pascal} : aucun champ déclaré — passe-les en arguments (ex : nodefony create entity ${pascal} title:string! body:text? views:int=0)`);
+	const timestamps = isUserEntity ? false : answers.timestamps !== false;
+	const softDelete = answers.softDelete === true;
+	const toList = (value) => Array.isArray(value) ? value.map(String) : typeof value === "string" && value.length > 0 ? [value] : [];
+	const indexes = [...parseEntityIndexes(toList(answers.index), fields, {
+		timestamps,
+		softDelete
+	}), ...parseEntityIndexes(toList(answers.uniqueIndex), fields, {
+		timestamps,
+		softDelete
+	}, true)];
+	const codegen = buildEntityCodegen(fields, {
+		dialect,
+		id,
+		timestamps,
+		softDelete,
+		table,
+		indexes,
+		columnCase,
+		idName
+	});
+	const sortable = [
+		"id",
+		...fields.filter((f) => f.type !== "json").map((f) => f.name),
+		...timestamps ? ["createdAt", "updatedAt"] : []
+	];
+	const filterDef = (f) => {
+		if (f.type === "bool") return "\"boolean\"";
+		if (f.type === "enum" && f.values?.length) return JSON.stringify(f.values).replace(/","/g, "\", \"");
+		if (f.type === "ref") return id === "serial" ? "\"int\"" : "\"string\"";
+		return null;
+	};
+	const filters = fields.map((f) => ({
+		name: f.name,
+		def: filterDef(f)
+	})).filter((e) => e.def !== null);
+	const defaultOrder = timestamps ? "[[\"createdAt\", \"DESC\"], [\"id\", \"DESC\"]]" : "[[\"id\", \"DESC\"]]";
+	for (const field of fields) {
+		if (field.type !== "ref" || !field.target) continue;
+		const targetFile = path.join(target.dir, "nodefony", "entity", `${field.target}.ts`);
+		if (!writer.exists(targetFile)) throw new Error(`create entity ${pascal} : la relation « ${field.name}:ref:${field.target} » vise une entité qui n'existe pas dans ${target.name} — crée-la d'abord (nodefony create entity ${field.target} …), puis relance`);
+	}
+	const relations = fields.filter((f) => f.type === "ref" && f.target).map((f) => ({
+		field: f.name,
+		target: f.target,
+		type: "many-to-one",
+		foreignKey: f.name
+	}));
+	const route = String(answers.route) || `/api/${pluralize(kebab)}`;
+	const sample = {};
+	const factory = [];
+	for (const f of fields) {
+		if (f.nullable) continue;
+		const { fixed, expr } = sampleValue(f, id);
+		sample[f.name] = fixed;
+		factory.push(`${f.name}: ${expr}`);
+	}
+	const comparableField = fields.find((f) => !f.nullable && f.type !== "date" && f.type !== "json" && f.type !== "ref" && f.type !== "enum")?.name ?? null;
+	const eta = new Eta(ETA_OPTIONS);
+	const written = [];
+	const data = {
+		pascal,
+		camel,
+		kebab,
+		table,
+		route,
+		connector,
+		dialect,
+		moduleName: target.kind === "app" ? "app" : String(target.name),
+		curlBody: JSON.stringify(sample),
+		sampleFactory: `{ ${factory.join(", ")} }`,
+		comparableField,
+		hasUnique: fields.some((f) => f.unique),
+		sortProbe: comparableField ?? "id",
+		filterProbe: filterProbe(fields),
+		malformedProbe: malformedProbe(filters),
+		relationTargets: [...new Set(fields.filter((f) => f.type === "ref" && f.target).map((f) => f.target))],
+		timestamps,
+		softDelete,
+		sortable,
+		filters,
+		defaultOrder,
+		relations,
+		hasSecurity: targetDeps.has("@nodefony/security"),
+		...codegen
+	};
+	const templates = path.join(packageRoot, "templates", "entity");
+	const tokens = {
+		__PASCAL__: pascal,
+		__KEBAB__: kebab
+	};
+	const service = isUserEntity ? false : answers.service !== false;
+	const controller = service && answers.controller !== false;
+	renderLayer(eta, path.join(templates, "base"), target.dir, data, written, writer, tokens);
+	if (service) renderLayer(eta, path.join(templates, "service"), target.dir, data, written, writer, tokens);
+	if (controller) renderLayer(eta, path.join(templates, "controller"), target.dir, data, written, writer, tokens);
+	if (!isUserEntity && answers.tests !== false) renderLayer(eta, path.join(templates, "tests"), target.dir, data, written, writer, tokens);
+	if (target.kind === "module") {
+		const peer = manifest["peerDependencies"] ??= {};
+		let touched = false;
+		for (const brick of ["@nodefony/orm-core", "@nodefony/drizzle"]) if (!targetDeps.has(brick)) {
+			peer[brick] = "*";
+			touched = true;
+		}
+		if (touched) {
+			writer.write(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`);
+			written.push("package.json");
+		}
+	}
+	const indexPath = path.join(target.dir, "index.ts");
+	wireEntitiesDecorator(indexPath, `${pascal}Entity`, `./nodefony/entity/${pascal}`, writer, isUserEntity);
+	if (controller) wireDecoratorList(indexPath, "controllers", `${pascal}Controller`, `./nodefony/controllers/${pascal}Controller`, writer);
+	written.push("index.ts");
+	const writtenMode = readConnectors(projectRoot, writer).find((c) => c.name === connector)?.ddl;
+	const schemaBuiltAtBoot = writtenMode !== "none" && writtenMode !== "migrate";
+	const notes = [
+		...ormRuntimeNote,
+		schemaBuiltAtBoot ? `table ${table} sur le connecteur « ${connector} » (${dialect}) — créée au prochain boot en développement` : `table ${table} sur le connecteur « ${connector} » (${dialect}, schéma : ${writtenMode}) — le démarrage ne la crée PAS`,
+		...schemaBuiltAtBoot ? [`⚠ en dev, un champ ajouté qui accepte le vide est posé au prochain boot ; un champ OBLIGATOIRE ne l'est pas — « nodefony orm:reset », ou une migration`, `⚠ production : appliquer les migrations AVANT le déploiement (« nodefony orm:migrate »), jamais depuis le processus qui sert le trafic`] : [
+			`→ écrire la migration : nodefony orm:generate --name <nom>`,
+			`→ l'appliquer : nodefony orm:migrate${connector === "default" ? "" : ` --connector ${connector}`}`,
+			`⚠ tant qu'elle n'est pas appliquée, la colonne n'existe pas en base — les requêtes qui la lisent échoueront`
+		]
+	];
+	if (controller) notes.push(`REST ${route} (GET liste paginée/POST) · ${route}/{id} (GET/PUT/PATCH/DELETE) — les lectures répondent AUSSI par la socket`);
+	if (!service) notes.push("service et controller non générés (--no-service)");
+	else if (!controller) notes.push("controller non généré (--no-controller)");
+	return {
+		dest: target.dir,
+		files: written.sort(),
+		linked: [],
+		notes,
+		depsAdded
+	};
+}
+/**
+* Ajoute une entité au décorateur `@entities([...])` de la cible — **en le créant
+* s'il n'existe pas encore**.
+*
+* Différence avec `wireDecoratorList` : une app n'a aucune raison de porter un
+* `@entities([])` vide tant qu'elle n'a pas d'entité, et les apps déjà générées n'en
+* ont pas. Plutôt que d'exiger une ancre (throw) ou de l'imposer à tous les templates,
+* on **pose le décorateur au premier usage**, juste au-dessus de `@controllers` (ou de
+* la déclaration de classe s'il n'y en a pas).
+*
+* Édition textuelle conservatrice : toute ambiguïté fait échouer avec un geste à
+* appliquer à la main, plutôt que de corrompre le fichier.
+*
+* @param indexPath - `index.ts` de la cible.
+* @param className - nom du descripteur (`PostEntity`).
+* @param importPath - chemin relatif du descripteur.
+* @throws si l'entité est déjà référencée, ou si aucun point d'insertion n'est trouvé.
+*/
+/**
+* Position d'insertion devant la classe `… extends Module` — décorateurs de
+* classe COMPRIS, puisque `@entities([…])` doit se poser au-dessus d'eux.
+*
+* Volontairement PAS une expression régulière. Le motif naturel
+* (`(?:@\w+\([\s\S]*?\)\s*)*class …`) est ambigu — le contenu paresseux d'un
+* décorateur peut se découper de plusieurs façons entre deux itérations — donc
+* exponentiel au backtracking : mesuré ici, 26 décorateurs sans classe à trouver
+* coûtaient 636 ms, et chaque paire supplémentaire multipliait par ~3,5. Or le
+* pire cas EST le cas d'échec prévu par l'appelant (ancre introuvable) : la
+* commande figeait au lieu de rendre son geste manuel.
+*
+* Le balayage ci-dessous remonte les décorateurs un par un en appariant les
+* parenthèses — linéaire, et correct sur un décorateur qui en contient
+* lui-même (`@entities([defineEntity(x)])`).
+*
+* @param source - contenu de l'`index.ts` de la cible.
+* @returns l'index d'insertion, ou `undefined` si aucune classe `extends Module`.
+*/
+function findModuleClassAnchor(source) {
+	const match = /^class\s+\w+\s+extends\s+Module\b/mu.exec(source);
+	if (!match || match.index === void 0) return;
+	let at = match.index;
+	for (;;) {
+		let end = at - 1;
+		while (end >= 0 && /\s/u.test(source[end])) end--;
+		if (end < 0 || source[end] !== ")") return at;
+		let depth = 0;
+		let open = end;
+		for (; open >= 0; open--) {
+			const char = source[open];
+			if (char === ")") depth++;
+			else if (char === "(") {
+				depth--;
+				if (depth === 0) break;
+			}
+		}
+		if (open < 0) return at;
+		let name = open - 1;
+		while (name >= 0 && /[\w.]/u.test(source[name])) name--;
+		if (name < 0 || source[name] !== "@" || name === open - 1) return at;
+		at = name;
+	}
+}
+/**
+* Câble un descripteur d'entité au module de la cible.
+*
+* @param indexPath - `index.ts` de la cible (app racine ou module).
+* @param className - nom exporté du descripteur.
+* @param importPath - chemin d'import, en `/`.
+* @param writer - écrivain du scaffold (respecte `--dry-run`).
+* @param alreadyWiredIsNormal - `true` quand RÉGÉNÉRER l'entité est le geste
+*   attendu, et non un doublon. C'est le cas de l'utilisateur : son fichier
+*   PRESCRIT « relance la commande avec tes champs », et l'entité est déjà
+*   câblée depuis la naissance de l'application. Le refus reste entier pour
+*   toutes les autres : deux entités du même nom dans un registre PLAT font
+*   échouer le démarrage.
+* @throws Si le nom est déjà référencé hors de ce cas, ou si l'`index.ts` n'a
+*   aucun import où s'accrocher.
+*/
+function wireEntitiesDecorator(indexPath, className, importPath, writer, alreadyWiredIsNormal = false) {
+	const source = writer.read(indexPath);
+	if (new RegExp(`\\b${className}\\b`, "u").test(source)) {
+		if (alreadyWiredIsNormal) return;
+		throw new Error(`${className} est déjà référencé dans ${indexPath} — choisis un autre nom d'entité`);
+	}
+	const importLine = `import { ${className} } from "${importPath}";`;
+	const manual = `  ${importLine}\n  @entities([${className}]) sur la classe Module`;
+	const last = [...source.matchAll(/^import [^\n]*$/gmu)].at(-1);
+	if (!last || last.index === void 0) throw new Error(`aucun import trouvé dans ${indexPath} — ajoute à la main :\n${manual}`);
+	const importAt = last.index + last[0].length;
+	const listRe = decoratorListRe("entities");
+	if (listRe.test(source)) {
+		const withImport = source.slice(0, importAt) + `\n${importLine}` + source.slice(importAt);
+		const current = listRe.exec(withImport)[2].trim();
+		const wired = withImport.replace(listRe, `$1@entities([${current ? `${current.replace(/,\s*$/u, "")}, ` : ""}${className}])`);
+		writer.write(indexPath, wired);
+		return;
+	}
+	const anchorRe = /^@controllers\(/mu;
+	if ((anchorRe.exec(source)?.index ?? findModuleClassAnchor(source)) === void 0) throw new Error(`ni @controllers ni « class … extends Module » dans ${indexPath} — ajoute à la main :\n${manual}`);
+	const needsDecoratorImport = !/\bentities\b[^\n]*@nodefony\/orm-core/u.test(source);
+	const injected = `\n${importLine}` + (needsDecoratorImport ? `\nimport { entities } from "@nodefony/orm-core";` : "");
+	const withImports = source.slice(0, importAt) + injected + source.slice(importAt);
+	const shiftedAt = anchorRe.exec(withImports)?.index ?? findModuleClassAnchor(withImports);
+	if (shiftedAt === void 0) throw new Error(`point d'insertion perdu dans ${indexPath} — ajoute à la main :\n${manual}`);
+	const wired = withImports.slice(0, shiftedAt) + `@entities([${className}])\n` + withImports.slice(shiftedAt);
+	writer.write(indexPath, wired);
+}
+/**
+* Scaffold IN-PROJECT d'un frontend Vite (`create front`) : pose la coquille
+* HTML (la MÊME brique que `create app`), l'entry du framework choisi, le
+* controller de page (`renderDocument` + nonce CSP) et le registrar d'entry ;
+* câble `@controllers` et le hook `onKernelBoot` de la cible ; complète les
+* deps npm du framework (catalogue UNIQUE `FRONTEND_PARAMS`).
+*
+* @throws hors projet, cible inconnue, cible portant DÉJÀ un front
+*   (`frontend/index.html` — ce scaffold pose l'INITIAL, il ne fusionne pas),
+*   ou dep `@nodefony/frontend` absente de l'APPLICATION. Absente du seul module
+*   visé, elle y est POSÉE en peer : un workspace résout depuis l'arbre de
+*   l'app, et exiger une édition manuelle du `package.json` revenait à demander
+*   à la main ce que ce scaffold existe pour écrire.
+*/
+function runFrontScaffold(request, answers, packageRoot, writer) {
+	const projectRoot = findProjectRoot(request.dir);
+	if (!projectRoot) throw new Error("aucun projet Nodefony ici (nodefony.config.ts introuvable en remontant) — lance la commande depuis une app (créée par `nodefony create app`)");
+	const target = resolveScaffoldTarget(projectRoot, String(answers.module ?? ""), writer);
+	if (writer.exists(path.join(target.dir, "frontend", "index.html"))) throw new Error(`${target.name} porte déjà un front (frontend/index.html) — ce scaffold pose la coquille et l'entry INITIALES ; pour une page de plus, ajoute une entry au registerEntry existant et un controller de page`);
+	const manifestPath = path.join(target.dir, "package.json");
+	const manifest = JSON.parse(writer.read(manifestPath));
+	const targetDeps = new Set([
+		"dependencies",
+		"devDependencies",
+		"peerDependencies"
+	].flatMap((b) => Object.keys(manifest[b] ?? {})));
+	let addFrontendPeer = false;
+	if (!targetDeps.has("@nodefony/frontend")) {
+		const appDeps = readAppDependencyNames(projectRoot, writer);
+		if (target.kind === "module" && appDeps.has("@nodefony/frontend")) addFrontendPeer = true;
+		else throw new Error(`@nodefony/frontend manque dans ${target.name} — ajoute la dep + "@nodefony/frontend" au manifeste modules de nodefony.config.ts`);
+	}
+	const frontend = answers.frontend;
+	const front = FRONTEND_PARAMS[frontend];
+	const base = String(answers.name);
+	const pascal = toPascalCase(base);
+	const nameClass = `${pascal}Controller`;
+	const kebab = toKebabCase(base);
+	const route = String(answers.route) || `/${kebab}`;
+	const eta = new Eta(ETA_OPTIONS);
+	const written = [];
+	const data = {
+		nameClass,
+		pascal,
+		kebab,
+		entryName: kebab,
+		route,
+		frontend,
+		front,
+		appName: target.name
+	};
+	const tokens = {
+		__NAME__: nameClass,
+		__PASCAL__: pascal
+	};
+	renderLayer(eta, path.join(packageRoot, "templates", "shared", "front-shell"), target.dir, data, written, writer, tokens);
+	renderLayer(eta, path.join(packageRoot, "templates", "front", "base"), target.dir, data, written, writer, tokens);
+	renderLayer(eta, path.join(packageRoot, "templates", "shared", "front-registrar"), target.dir, data, written, writer, tokens);
+	renderLayer(eta, path.join(packageRoot, "templates", "front", frontend), target.dir, data, written, writer, tokens);
+	renderLayer(eta, path.join(packageRoot, "templates", "shared", "front-entry", frontend), target.dir, data, written, writer, tokens);
+	if (frontend === "angular") renderLayer(eta, path.join(packageRoot, "templates", "shared", "ng-app-tsconfig"), target.dir, data, written, writer, tokens);
+	if (frontend === "vue") renderLayer(eta, path.join(packageRoot, "templates", "shared", "vue-shim"), target.dir, data, written, writer, tokens);
+	if (frontend === "svelte") renderLayer(eta, path.join(packageRoot, "templates", "shared", "svelte-shim"), target.dir, data, written, writer, tokens);
+	const added = [];
+	const addDeps = (block, entries) => {
+		if (Object.keys(entries).length === 0) return;
+		const deps = manifest[block] ??= {};
+		for (const [name, version] of Object.entries(entries)) if (!targetDeps.has(name)) {
+			deps[name] = version;
+			added.push(name);
+		}
+	};
+	addDeps("dependencies", front.deps);
+	addDeps("devDependencies", front.devDeps);
+	if (addFrontendPeer) addDeps("peerDependencies", { "@nodefony/frontend": "*" });
+	if (added.length > 0) {
+		writer.write(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`);
+		written.push("package.json");
+	}
+	const indexPath = path.join(target.dir, "index.ts");
+	wireDecoratorList(indexPath, "controllers", nameClass, `./nodefony/controllers/${nameClass}`, writer);
+	const wireNote = wireKernelBootCall(indexPath, `register${pascal}Entry`, `./nodefony/frontend/register${pascal}Entry`, writer);
+	written.push("index.ts");
+	const notes = [
+		`page ${route} (GET — controller ${nameClass}, entry Vite « ${kebab} »)`,
+		...added.length > 0 ? [`deps ajoutées : ${added.join(", ")} → lance npm install`] : [],
+		...wireNote ? [wireNote] : []
+	];
+	return {
+		dest: target.dir,
+		files: written.sort(),
+		linked: [],
+		notes
+	};
+}
+/**
+* Câble un appel dans le hook `onKernelBoot()` de l'`index.ts` cible : import
+* de la fonction + soit INSERTION d'un hook complet (s'il n'existe pas — le
+* layout des index générés est connu), soit note actionnable (un hook existant
+* n'est JAMAIS édité : on ne réécrit pas du code utilisateur).
+*
+* @returns note à afficher si un geste manuel reste nécessaire, sinon `null`.
+*/
+function wireKernelBootCall(indexPath, fnName, importPath, writer) {
+	const source = writer.read(indexPath);
+	const importLine = `import { ${fnName} } from "${importPath}";`;
+	const last = [...source.matchAll(/^import [^\n]*$/gmu)].at(-1);
+	if (!last || last.index === void 0) return `ajoute à la main : ${importLine} + ${fnName}(this); dans onKernelBoot()`;
+	const importAt = last.index + last[0].length;
+	const withImport = source.slice(0, importAt) + `\n${importLine}` + source.slice(importAt);
+	if (/onKernelBoot\s*\(/u.test(withImport)) {
+		writer.write(indexPath, withImport);
+		return `onKernelBoot() existe déjà dans index.ts — ajoute : ${fnName}(this);`;
+	}
+	const hook = `
+  /**
+   * Déclare l'entry frontend auprès du FrontendService — AVANT
+   * onKernelReady pour que le superviseur Vite démarre avec elle.
+   */
+  override async onKernelBoot(): Promise<this> {
+    ${fnName}(this);\n    return this;\n  }\n`;
+	const closer = /\n\}\s*\n+export default /u.exec(withImport);
+	if (!closer || closer.index === void 0) {
+		writer.write(indexPath, withImport);
+		return `fin de classe introuvable dans index.ts — ajoute à la main le hook :\n  override async onKernelBoot(): Promise<this> { ${fnName}(this); return this; }`;
+	}
+	const wired = withImport.slice(0, closer.index) + hook + withImport.slice(closer.index + 1);
+	writer.write(indexPath, wired);
+	return null;
+}
+//#endregion
+export { DATABASE_PARAMS, FRONTEND_PARAMS, ensureWorkspaces, filterProbe, findModuleClassAnchor, findPackageRoot, findProjectRoot, getScaffoldContext, linkLocalDeps, listTargets, malformedProbe, resolveAnswers, resolveDatabase, resolveLocalWorkspaces, runScaffold, sampleValue, scaffoldCaps, toKebabCase, toPascalCase, wireCommandCall, wireDecoratorList, wireEntitiesDecorator, wireKernelBootCall, wireModuleManifest, wireRoleHierarchy, writeAgentPointers };