nodefony 7.0.2 → 10.0.0-alpha.2

package/dist/node/cli/create.js

@@ -0,0 +1,805 @@
+import { version } from "../package.js";
+import "./sysexits.js";
+import { chargePrompts } from "./prompts.js";
+import { printUsage, printUsageError } from "./usageReport.js";
+import { needsShell } from "./execPortable.js";
+import { findProjectRoot } from "./projectRoot.js";
+import { stripGlobalCliFlags } from "./globalFlags.js";
+import { syncSkillPointers } from "./aiSync.js";
+import { AGENT_TARGETS } from "./agentTargets.js";
+import { formatFilesOnDisk } from "./scaffold/format.js";
+import { diffLines } from "./scaffold/writer.js";
+import { COMMAND_PHASE_CHOICES, CONTROLLER_KIND_CHOICES, DATABASE_CHOICES, ENTITY_ID_CHOICES, FRONTEND_CHOICES, MODULE_CONTROLLER_CHOICES, PRESET_CHOICES, getScaffoldSpec } from "./scaffold/spec.js";
+import { findPackageRoot, getScaffoldContext, listTargets, resolveLocalWorkspaces, runScaffold } from "./scaffold/engine.js";
+import { runAiMcpCommand } from "./aiMcp.js";
+import { GIT_HOOKS_DIR } from "./gitHooksReport.js";
+import { installGitHooks } from "./gitHooks.js";
+import { askMissing, confirm } from "./scaffold/interactive.js";
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+//#region src/cli/create.ts
+/**
+* Adaptateur CLI du scaffold `nodefony create <type> [name]` — front n°1 et n°2
+* du moteur (`scaffold/engine.ts`, partagé avec Studio) :
+*
+*   - **CLI rapide** : tout est dit en flags (`create app x --preset minimal
+*     --frontend react --link`) → zéro question, scriptable.
+*   - **CLI interactif** (défaut en TTY) : les questions de la spec NON couvertes
+*     par les flags sont posées en readline natif, récap + confirmation.
+*   - Hors TTY (CI, spawn de test) : les défauts de la spec s'appliquent —
+*     comportement stable pour les scripts, `--yes` force la même chose en TTY.
+*
+* Pur outillage standalone (même famille que status/stop/completion) : AUCUN
+* boot kernel — cas nominal HORS projet : `npx nodefony create app mon-app`.
+*/
+/** Types de scaffold disponibles. */
+const CREATE_TYPES = [
+	"app",
+	"module",
+	"controller",
+	"service",
+	"front",
+	"entity",
+	"command"
+];
+/**
+* Parse l'argv complet du process après le mot `create`. Ne valide QUE la forme
+* des flags — les valeurs (nom, preset…) sont jugées par la spec du moteur.
+*
+* @returns la requête, ou un message d'usage si invalide
+*/
+function parseCreateArgv(argv) {
+	const at = argv.indexOf("create");
+	const rest = stripGlobalCliFlags(at === -1 ? [] : argv.slice(at + 1));
+	const positionals = [];
+	const answers = {};
+	let dir;
+	let force = false;
+	let yes = false;
+	let install = true;
+	let git = true;
+	let dryRun = false;
+	let describeJson = false;
+	let answersJson;
+	let help = false;
+	for (let i = 0; i < rest.length; i++) {
+		const word = rest[i];
+		if (word === "--help" || word === "-h") help = true;
+		else if (word === "--force" || word === "-f") force = true;
+		else if (word === "--yes" || word === "-y") yes = true;
+		else if (word === "--dry-run" || word === "-n") dryRun = true;
+		else if (word === "--describe-json") describeJson = true;
+		else if (word === "--answers-json") answersJson = rest[++i];
+		else if (word === "--no-install") install = false;
+		else if (word === "--no-git") git = false;
+		else if (word === "--git-hooks") answers.gitHooks = true;
+		else if (word === "--link") answers.link = true;
+		else if (word === "--no-link") answers.link = false;
+		else if (word === "--agents") answers.agents = (rest[++i] ?? "").split(/[\s,]+/u).map((c) => c.trim().toLowerCase()).filter((c) => c.length > 0 && c !== "none");
+		else if (word === "--preset") answers.preset = rest[++i];
+		else if (word === "--frontend") answers.frontend = rest[++i];
+		else if (word === "--database") answers.database = rest[++i];
+		else if (word === "--kind") answers.kind = rest[++i];
+		else if (word === "--controller") answers.controller = rest[++i];
+		else if (word === "--description") answers.description = rest[++i];
+		else if (word === "--service") {
+			const next = rest[i + 1];
+			answers.service = true;
+			if (next !== void 0 && !next.startsWith("-")) answers.serviceName = rest[++i];
+		} else if (word === "--no-service") answers.service = false;
+		else if (word === "--command") answers.command = true;
+		else if (word === "--no-command") answers.command = false;
+		else if (word === "--phase") answers.phase = rest[++i];
+		else if (word === "--route") answers.route = rest[++i];
+		else if (word === "--module") answers.module = rest[++i];
+		else if (word === "--role") answers.role = rest[++i];
+		else if (word === "--inject") answers.inject = rest[++i];
+		else if (word === "--no-controller") answers.controller = false;
+		else if (word === "--fields") answers.fields = rest[++i];
+		else if (word === "--id") answers.id = rest[++i];
+		else if (word === "--connector") answers.connector = rest[++i];
+		else if (word === "--dialect") answers.dialect = rest[++i];
+		else if (word === "--table") answers.table = rest[++i];
+		else if (word === "--column-case") answers.columnCase = rest[++i];
+		else if (word === "--id-name") answers.idName = rest[++i];
+		else if (word === "--index" || word === "--unique") {
+			const value = rest[++i];
+			if (value !== void 0) {
+				const key = word === "--index" ? "index" : "uniqueIndex";
+				const current = answers[key];
+				answers[key] = [...Array.isArray(current) ? current : [], value];
+			}
+		} else if (word === "--soft-delete") answers.softDelete = true;
+		else if (word === "--no-timestamps") answers.timestamps = false;
+		else if (word === "--no-tests") answers.tests = false;
+		else if (word === "--dir") dir = rest[++i];
+		else if (word.startsWith("-")) return { error: `option inconnue : ${word}` };
+		else positionals.push(word);
+	}
+	const [type, name, ...extra] = positionals;
+	if (help) return {
+		help,
+		answers,
+		force,
+		yes,
+		install,
+		git,
+		dryRun,
+		describeJson
+	};
+	if (type !== void 0 && !CREATE_TYPES.includes(type)) return { error: `type requis : ${CREATE_TYPES.join(" | ")} (reçu : ${type})` };
+	if (type === void 0 && !describeJson) return { error: `type requis : ${CREATE_TYPES.join(" | ")} (reçu : rien)` };
+	if (answersJson === void 0 && rest.includes("--answers-json")) return { error: "--answers-json attend un fichier, ou - pour l'entrée standard" };
+	if (name !== void 0) answers.name = name;
+	if (type === "entity" && extra.length > 0) answers.fields = extra.join(" ");
+	return {
+		help,
+		type,
+		answers,
+		dir,
+		force,
+		yes,
+		install,
+		git,
+		dryRun,
+		describeJson,
+		answersJson
+	};
+}
+const PAR_TYPE = `  app        : [--preset <${PRESET_CHOICES.join("|")}>] [--frontend <${FRONTEND_CHOICES.join("|")}>]\n               [--agents <liste|none>] — agents de dev à câbler (défaut : aucun)\n               [--database <${DATABASE_CHOICES.join("|")}>] — le compose ne porte QUE ce service\n               [--link|--no-link] [--no-install] [--no-git] [--git-hooks]\n  module     : [--controller <${MODULE_CONTROLLER_CHOICES.join("|")}>] [--no-service] [--command]\n               [--frontend <${FRONTEND_CHOICES.join("|")}>] [--description "…"] [--no-install]\n  controller : [--kind <${CONTROLLER_KIND_CHOICES.join("|")}>] [--route </api/x>] [--module <nom>]\n               [--role ROLE_X] — réserve TOUT le controller à cette habilitation\n                 (@IsGranted de classe) et déclare le rôle dans roleHierarchy :\n                 l'administrateur en hérite, sans qu'on ait à le lui attribuer\n  service    : [--inject <AutreService>] [--description "…"] [--module <nom>]\n               classe @injectable, sans dépendance à un config.ts — pour la découvrir, imite-la\n               --inject : dépendance déclarée au CONSTRUCTEUR (@inject + appel), pas container.get\n  front      : [--frontend <react|vue|angular|svelte>] [--route </page>] [--module <nom>]\n  entity     : [champs…] [--id <${ENTITY_ID_CHOICES.join("|")}>] [--soft-delete] [--no-timestamps]\n               [--no-controller] [--no-service] [--no-tests] [--route </api/x>] [--module <nom>]\n               [--connector <nom>] [--dialect <sqlite|postgres|mysql>]\n               [--index "colA,colB"] [--unique "colA,colB"] — répétables, un par index\n               [--table <nom_sql>] [--column-case <camel|snake>] [--id-name <colonne>]\n                 — pour épouser une table EXISTANTE ; les propriétés TS ne changent pas\n               ex : nodefony create entity Website name:string domain:string \\\n                      --table website --column-case snake --id-name website_id\n               champs : nom:type[?|!][:index] — types : string(n) text int float bool json date uuid char(n) decimal(p,s) ref:<Entité>\n               ex : nodefony create entity Post title:string! content:text views:int author:ref:User\n               ex : nodefony create entity Event siteId:uuid path:string --index "siteId,createdAt"\n  command    : [--phase <${COMMAND_PHASE_CHOICES.join("|")}>] [--description "…"] [--service] [--module <nom>]\n               nom = l'ACTION ; la commande vaut <module>:<action> (ex : blog:publish)\n               (types controller/service/front/entity/command : dans un projet existant — app racine ou module)\n  Sans flags dans un terminal → mode interactif (questions + récap).\n  Mode machine (agents, scripts) :\n    --describe-json                  types, questions, valeurs permises et cibles du projet, en JSON\n    --answers-json <fichier|->       réponses en JSON (- = entrée standard) ; les flags l'emportent\n    --dry-run                        le plan (fichiers créés + diff des réécritures), sans rien écrire\n`;
+/** La page d'aide — `nodefony create --help`, et le rappel après un refus. */
+const PAGE = {
+	command: "nodefony create",
+	tagline: "engendre du code conforme au framework : une application, un module, un controller, un service, un front, une entité, une commande",
+	synopsis: [`nodefony create <${CREATE_TYPES.join("|")}> [nom] [options]`, "nodefony create --describe-json"],
+	sections: [{
+		title: "CE QUE CHAQUE TYPE ACCEPTE",
+		lines: PAR_TYPE.split("\n").filter((l) => l !== "")
+	}],
+	options: [
+		{
+			term: "--dir <chemin>",
+			text: "dossier cible (défaut : ./<nom>)"
+		},
+		{
+			term: "-f, --force",
+			text: "accepte un dossier cible non vide"
+		},
+		{
+			term: "-y, --yes",
+			text: "prend les défauts de la spec (saute l'interactif)"
+		},
+		{
+			term: "-n, --dry-run",
+			text: "le plan, sans rien écrire"
+		},
+		{
+			term: "--describe-json",
+			text: "types, questions, valeurs permises et cibles du projet, en JSON — la porte MACHINE, pour un agent ou un script"
+		},
+		{
+			term: "--answers-json <f>",
+			text: "réponses en JSON (`-` = entrée standard) ; les drapeaux l'emportent"
+		}
+	],
+	examples: [
+		{
+			term: "nodefony create app mon-app",
+			text: "une application neuve, hors de tout projet"
+		},
+		{
+			term: "nodefony create entity Post title:string content:text",
+			text: "une entité, son repository, son controller et ses tests"
+		},
+		{
+			term: "nodefony create --describe-json | jq .",
+			text: "ce que le générateur sait faire, pour un agent"
+		}
+	],
+	exitCodes: [{
+		term: "73",
+		text: "le dossier cible ne peut pas être créé (EX_CANTCREAT)"
+	}],
+	footer: "Sans drapeau dans un terminal, elle passe en mode interactif : les questions de la spec, puis un récapitulatif avant d'écrire."
+};
+/**
+* Décrit le scaffold en JSON — la porte MACHINE de `nodefony create`.
+*
+* POURQUOI : un agent qui développe dans une app Nodefony n'a que deux façons
+* d'obtenir du code conforme — imiter des fichiers existants (et se tromper dès
+* que l'exemple vieillit), ou APPELER le générateur. La seconde n'est possible
+* que si l'outil sait dire ce qu'il attend : types disponibles, questions,
+* valeurs permises, défauts. C'est exactement ce que la spec déclarative
+* contient déjà ; il ne manquait que la porte.
+*
+* Le format est additif : `types` décrit les questions, `project` décrit où l'on
+* se trouve — et son `context` porte ce que seul le projet sait (connecteurs
+* déclarés, entités déjà créées, traduction des types par moteur). Une question
+* marquée `optionsFrom` s'y réfère : ses réponses valides sont là, pas dans la
+* spec, parce qu'elles changent d'un projet à l'autre.
+*/
+function describeScaffold(type) {
+	const projectRoot = findProjectRoot(process.cwd());
+	return `${JSON.stringify({
+		nodefony: version,
+		types: getScaffoldSpec(type),
+		caps: { hasCheckout: resolveLocalWorkspaces(findPackageRoot()) !== null },
+		project: projectRoot ? {
+			root: projectRoot,
+			targets: listTargets(projectRoot).map((t) => ({
+				kind: t.kind,
+				name: t.name
+			})),
+			context: getScaffoldContext(projectRoot)
+		} : null,
+		usage: {
+			run: "nodefony create <type> <name> [flags]",
+			answers: "nodefony create <type> --answers-json - (réponses JSON sur l'entrée standard ; les flags l'emportent)",
+			preview: "ajouter --dry-run pour obtenir le plan sans rien écrire"
+		}
+	}, null, 2)}\n`;
+}
+/**
+* Réponses lues depuis `--answers-json` (fichier, ou `-` = entrée standard).
+*
+* Une clé hors spec est REFUSÉE plutôt qu'ignorée : `resolveAnswers` ne
+* conserve que les clés déclarées, si bien qu'un `"preset"` mal orthographié
+* produirait un scaffold silencieusement différent de celui demandé — le pire
+* retour possible pour un appelant automatique, qui n'a pas d'yeux pour
+* relire le résultat.
+*
+* @throws Error si la source est illisible, le JSON invalide, ou une clé inconnue
+*/
+function readAnswersJson(source, type) {
+	const raw = source === "-" ? readFileSync(0, "utf8") : readFileSync(source, "utf8");
+	let parsed;
+	try {
+		parsed = JSON.parse(raw);
+	} catch (e) {
+		throw new Error(`--answers-json : JSON invalide (${e.message})`, { cause: e });
+	}
+	if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) throw new Error("--answers-json : un objet de réponses est attendu");
+	const [spec] = getScaffoldSpec(type);
+	const known = new Set(spec.questions.map((q) => q.key));
+	const answers = {};
+	for (const [key, value] of Object.entries(parsed)) {
+		if (!known.has(key)) throw new Error(`--answers-json : clé inconnue « ${key} » pour ${type} — attendues : ${[...known].join(", ")}`);
+		if (typeof value !== "string" && typeof value !== "boolean") throw new Error(`--answers-json : « ${key} » doit être une chaîne ou un booléen`);
+		answers[key] = value;
+	}
+	return answers;
+}
+/** Lignes de diff affichées par fichier réécrit, avant troncature annoncée. */
+const DRY_RUN_DIFF_LINES = 20;
+/**
+* Rend le plan d'un `--dry-run` : ce qui serait créé, et surtout le DIFF de ce
+* qui serait réécrit.
+*
+* Les créations sont listées à plat (leur contenu n'écrase rien, l'inventaire
+* suffit) ; les réécritures sont les seules opérations qui touchent au travail
+* existant — c'est là que la simulation a une valeur, donc c'est là qu'on
+* dépense de la place.
+*/
+function renderDryRun(changes, notes) {
+	const rel = (file) => path.relative(process.cwd(), file) || ".";
+	const created = changes.filter((c) => c.kind === "create");
+	const rewritten = changes.filter((c) => c.kind === "overwrite");
+	let out = `\n🔍 simulation (--dry-run) — RIEN n'a été écrit\n\n  ${created.length} fichier(s) à créer, ${rewritten.length} à réécrire\n`;
+	if (created.length > 0) out += `\nCréés :\n${created.map((c) => `  + ${rel(c.path)}`).join("\n")}\n`;
+	for (const change of rewritten) {
+		const lines = diffLines(change.previous ?? "", change.content).filter((l) => l.kind !== "keep");
+		const shown = lines.slice(0, DRY_RUN_DIFF_LINES);
+		out += `\nRéécrit : ${rel(change.path)}\n` + shown.map((l) => `  ${l.kind === "add" ? "+" : "-"} ${l.text}`).join("\n") + (lines.length > shown.length ? `\n  … ${lines.length - shown.length} ligne(s) de plus\n` : "\n");
+	}
+	if (notes && notes.length > 0) out += `\nCe que l'exécution dirait :\n${notes.map((n) => `  ${n}`).join("\n")}\n`;
+	return out;
+}
+/**
+* `npm install` dans l'app générée (sortie streamée — le dev voit npm
+* travailler, pas un silence de 60 s). Échec = code retourné, l'appelant
+* décide (l'app EST générée : on n'échoue pas tout le create pour un réseau).
+*/
+function runInstall(dest) {
+	process.stdout.write(`\n⏳ npm install (${path.basename(dest)})…\n`);
+	return spawnSync("npm", ["install"], {
+		cwd: dest,
+		stdio: "inherit",
+		shell: needsShell("npm")
+	}).status === 0;
+}
+/**
+* Met en forme les fichiers que le scaffold vient d'écrire, après l'installation.
+*
+* Le formatage de la transaction ({@link formatScaffoldOutput}) ne peut rien
+* pour une app NEUVE : à l'instant où ses fichiers sont rendus, `npm install`
+* n'a pas encore tourné et le projet n'a aucun prettier à emprunter. C'est
+* pourtant le cas qui compte le plus — l'application qu'un utilisateur reçoit.
+*
+* 🔴 **Bornée aux fichiers ÉCRITS.** La première version passait `--write .` au
+* binaire du projet : sur `create module`, cela reformatait le dépôt ENTIER de
+* l'utilisateur, code écrit à la main compris. Un générateur met en forme ce
+* qu'il produit, jamais ce qu'il trouve.
+*
+* Silencieux et non bloquant : une app non formatée reste une app qui marche.
+*
+* @param dest - racine du projet (recherche de prettier).
+* @param files - chemins RELATIFS rendus par le scaffold.
+*/
+function runFormat(dest, files) {
+	formatFilesOnDisk(files.map((f) => path.join(dest, f)), dest);
+}
+/**
+* Le code de sortie de `create`, décidé à part — parce qu'il se teste.
+*
+* Le défaut qu'il ferme : la commande affichait « npm run build a échoué »
+* puis rendait **0**. L'application existait bien, c'est vrai — mais elle
+* n'était PAS utilisable, et aucun automate ne pouvait le savoir : ni une
+* chaîne d'intégration continue, ni un banc, ni un agent qui enchaîne. C'est
+* exactement ce qui a laissé le front d'une application générée ne pas se
+* bâtir sans que rien ne tombe, le message se noyant dans la sortie.
+*
+* La règle : **ce qui est ÉCRIT reste écrit** (les fichiers ne sont pas
+* retirés, les prochaines étapes sont affichées, `npm run build` y figure),
+* mais le code de sortie DIT qu'il reste quelque chose à faire.
+*
+* L'installation sautée (`--no-install`) ne compte pas comme un échec : rien
+* n'a été tenté, et la commande l'annonce dans ses prochaines étapes.
+*
+* 🔴 **Sautée et ratée sont deux états, pas un booléen.** Les deux étapes
+* étaient rendues par `boolean`, où `false` disait à la fois « on ne l'a pas
+* lancée » et « on l'a lancée et elle a échoué ». Une installation ratée
+* tombait donc du bon côté : code 0. Or elle emporte TOUT ce qui la suit — le
+* formatage, le build, la migration initiale — et l'utilisateur reçoit une
+* application qui ne peut pas démarrer, sous un succès. Constaté sur le décor
+* du banc de découvrabilité, dont l'application témoin n'avait jamais eu de
+* `dist/` ni de `migrations/` : le manifeste pointait encore vers un registre
+* où aucun paquet `@nodefony/*` n'est publié.
+*
+* @param install - l'installation des dépendances : sautée, réussie, échouée.
+* @param build - `npm run build` : sauté (l'install n'a pas eu lieu), réussi,
+*   échoué.
+* @returns `OK`, ou `SOFTWARE` dès qu'une étape TENTÉE a échoué.
+*/
+function createExitCode(install, build) {
+	return install === "failed" || build === "failed" ? 70 : 0;
+}
+/**
+* `npm run build` dans l'app générée — le runtime charge `dist/index.js`
+* (garde fail-loud « NON CONSTRUIT » au boot) : sans ce build, le premier
+* `npm run dev` échoue. Suit l'install (pas de node_modules = pas de build) ;
+* `dist/` est gitignoré → n'entre pas dans le premier commit.
+*/
+function runBuild(dest) {
+	process.stdout.write(`\n⏳ npm run build (${path.basename(dest)})…\n`);
+	return spawnSync("npm", ["run", "build"], {
+		cwd: dest,
+		stdio: "inherit",
+		shell: needsShell("npm")
+	}).status === 0;
+}
+/**
+* Le paquet qui porte les migrations SQL.
+*
+* Nommé UNE seule fois : deux endroits demandent « cette application a-t-elle
+* un ORM ? » — celui qui ÉCRIT la migration, et celui qui l'ANNONCE quand elle
+* n'a pas pu l'être. Écrit deux fois, il divergerait au premier renommage.
+*/
+const ORM_PACKAGE = "@nodefony/drizzle";
+/**
+* L'application générée DÉCLARE-t-elle un ORM SQL ?
+*
+* Se lit dans le MANIFESTE, jamais dans `node_modules` : la question se pose
+* précisément quand rien n'est installé — `--no-install`, ou un build en
+* échec. C'est là que la migration manque, et c'est là que personne ne le
+* disait.
+*
+* @param dest - racine de l'application générée.
+* @returns `true` si le manifeste déclare le paquet d'ORM.
+*/
+function appDeclareUnOrm(dest) {
+	try {
+		return JSON.parse(readFileSync(path.join(dest, "package.json"), "utf8")).dependencies?.[ORM_PACKAGE] !== void 0;
+	} catch {
+		return false;
+	}
+}
+/**
+* Écrit la PREMIÈRE migration de l'application — celle de son entité `User`.
+*
+* ## Pourquoi une application doit naître avec sa migration
+*
+* L'identité appartient à l'application : c'est elle qui déclare la table
+* `User`, donc elle qui en porte la migration. En développement, le schéma est
+* dérivé du code et rien ne manque — c'est en PRODUCTION que le trou apparaît,
+* là où personne ne crée la table : le premier déploiement s'arrête sur
+* « table absente : User », pour un geste que rien n'imposait. Livrer l'entité
+* sans sa migration, c'est livrer la moitié qui se voit.
+*
+* ## Pourquoi la migration est GÉNÉRÉE, jamais recopiée dans un gabarit
+*
+* Un gabarit SQL figé dirait ce que l'entité disait le jour où on l'a écrit. Le
+* générateur, lui, lit l'entité qui vient d'être rendue — avec le dialecte figé
+* à la création, et les champs que l'utilisateur a demandés. Une source unique,
+* celle qui écrira aussi les migrations suivantes.
+*
+* ## Écrite, puis APPLIQUÉE
+*
+* Les deux, et dans la foulée : une application dont les fichiers de migration
+* existent mais dont la base ne les a jamais vus est à mi-chemin, et c'est le
+* pire des deux états. Son premier démarrage en développement dérive le schéma
+* du code, les tables apparaissent sans historique, et tout ce qui interroge
+* cet état ensuite accuse à juste titre — `doctor --live` en tête.
+*
+* ## Quand elle ne peut pas être écrite
+*
+* La commande démarre l'application, et le démarrage OUVRE la connexion : sans
+* base joignable, elle s'arrête avant d'exécuter le verbe. C'est le cas d'un
+* profil qui déclare un serveur qui n'existe pas encore. L'échec est alors DIT,
+* avec le geste exact — jamais avalé : une application qui croit avoir sa
+* migration et ne l'a pas est exactement le défaut qu'on répare ici.
+*
+* @param dest - racine de l'application générée.
+* @returns le verdict et sa ligne d'affichage, ou `null` si l'application n'a
+*          pas d'ORM. Le booléen n'est pas décoratif : c'est lui qui décide si
+*          les prochaines étapes doivent réclamer le geste — le lire dans le
+*          texte de la note le rendrait dépendant de sa formulation.
+*/
+function runInitialMigration(dest) {
+	if (!existsSync(path.join(dest, "node_modules", ORM_PACKAGE))) return null;
+	process.stdout.write(`\n⏳ migration initiale (orm:generate)…\n`);
+	const r = spawnSync("npm", [
+		"exec",
+		"--",
+		"nodefony",
+		"orm:generate",
+		"--name",
+		"init"
+	], {
+		cwd: dest,
+		encoding: "utf8",
+		shell: needsShell("npm"),
+		env: {
+			...process.env,
+			NODE_ENV: "production",
+			NF_STORE: "memory"
+		}
+	});
+	if (r.status === 0) {
+		if (spawnSync("npm", [
+			"exec",
+			"--",
+			"nodefony",
+			"orm:migrate"
+		], {
+			cwd: dest,
+			encoding: "utf8",
+			shell: needsShell("npm"),
+			env: {
+				...process.env,
+				NODE_ENV: "production",
+				NF_STORE: "memory"
+			}
+		}).status === 0) return {
+			written: true,
+			note: "écrite et appliquée (migrations/)"
+		};
+		return {
+			written: true,
+			note: "écrite (migrations/), NON appliquée — lance « nodefony orm:migrate » quand ta base répond"
+		};
+	}
+	return {
+		written: false,
+		note: `NON écrite (${`${r.stdout ?? ""}${r.stderr ?? ""}`.includes("ECONNREFUSED") ? "base injoignable" : `code ${String(r.status)}`}) — lance « nodefony orm:generate --name init » puis « nodefony orm:migrate » quand ta base répond`
+	};
+}
+/**
+* Pose les pointeurs vers les skills d'agent livrés par les paquets installés.
+*
+* **Pourquoi ici, et pas par un `postinstall`** : `--ignore-scripts` est courant
+* (intégration continue, politiques d'entreprise), les scripts d'installation
+* sont un vecteur d'attaque connu de l'écosystème npm, et écrire dans un dossier
+* VERSIONNÉ à chaque installation produirait des différences surprises. Le
+* scaffold pose une fois, `npx nodefony ai:sync` remet à jour quand on le
+* demande.
+*
+* **Pourquoi APRÈS l'install et AVANT le premier commit** : les skills vivent
+* dans `node_modules`, il n'y a rien à découvrir tant qu'il n'existe pas ; et
+* ces pointeurs sont faits pour être VERSIONNÉS — l'équipe et l'intégration
+* continue disposent alors des mêmes skills que celui qui a créé l'app.
+*
+* Sans ce geste, le lot ne servirait qu'à celui qui connaît déjà `ai:sync` — or
+* personne n'apprend un verbe absent.
+*
+* @param dest - racine de l'app générée.
+* @returns la note à afficher. Ne lève JAMAIS : une application entièrement
+*   générée ne s'annule pas parce qu'un dossier de skills est illisible.
+*/
+function poseSkillPointers(dest) {
+	try {
+		const plan = syncSkillPointers(dest);
+		if (plan.skills.length === 0) return `aucun skill livré par les paquets installés → npx nodefony ai:sync après un npm install`;
+		return `${plan.skills.length} dans ${plan.directory}/ (${plan.skills.map((s) => s.name).join(", ")}) — commite-les`;
+	} catch (e) {
+		return `non posés (${e.message}) → npx nodefony ai:sync`;
+	}
+}
+/**
+* Un type manquant se DEMANDE-t-il, ou l'usage est-il la bonne réponse ? PURE.
+*
+* Trois conditions, et chacune dit quelque chose de différent :
+* - l'erreur est bien « aucun type » — un type FAUTIF (`create ap`) se corrige,
+*   il ne se remplace pas par une question qui masquerait la faute de frappe ;
+* - un terminal répond en face — sans lui, une question est un blocage muet ;
+* - `--yes` n'a pas été demandé : il dit « ne me demande rien », et le
+*   respecter vaut mieux que de rendre service.
+*
+* @param error - le motif rendu par l'analyse de la ligne de commande.
+* @param ctx - terminal disponible, et présence de `--yes`.
+*/
+function shouldAskForType(error, ctx) {
+	return error.includes("reçu : rien") && ctx.isTTY && !ctx.yes;
+}
+/**
+* Description courte d'un type de scaffold — celle de la SPEC, jamais une
+* seconde version : deux listes de types divergeraient au premier ajout.
+*/
+function descriptionType(type) {
+	const [spec] = getScaffoldSpec(type);
+	return spec?.description ?? type;
+}
+/**
+* Décide si `create app` CÂBLE la porte MCP chez les agents choisis. PURE.
+*
+* Deux refus, deux raisons qui n'ont rien à voir :
+* - **aucun agent choisi** — et c'est le DÉFAUT (la question de la spec part
+*   vide). Déclarer une porte chez un agent ÉCRIT dans la configuration d'un
+*   autre outil : rien de coché, rien d'écrit, en terminal comme ailleurs.
+*   C'est le choix explicite qui autorise, pas la présence d'un humain — ce
+*   qui rend le geste servable par Studio, qui n'est pas un terminal.
+* - **app ni installée ni construite** (`--no-install`, ou une install en
+*   échec) : `ai:mcp` enchaîne sur l'émission du jeton, qui DÉMARRE le kernel.
+*   Sans `node_modules` ni `dist`, on provoquerait soi-même l'échec — le geste
+*   est alors NOMMÉ plutôt que joué.
+*
+* @param ctx - nombre d'agents choisis, et état réel de l'app générée.
+* @returns la proposition, ou le motif du refus (affiché tel quel).
+*/
+function mcpWiringPlan(ctx) {
+	if (ctx.chosen === 0) return {
+		propose: false,
+		pattern: "aucun agent choisi"
+	};
+	if (!ctx.installed || !ctx.built) return {
+		propose: false,
+		pattern: "agents choisis mais app ni installée ni construite — l'émission du jeton démarre le kernel ; à rejouer : npx nodefony ai:mcp"
+	};
+	return { propose: true };
+}
+/**
+* Traduit le choix d'agents de développement en appel `ai:mcp` — PURE.
+*
+* ⭐ **Ce qui se choisit, c'est l'AGENT ; la porte MCP vient AVEC.** Demander
+* « veux-tu déclarer une porte MCP ? » posait la question à l'envers : personne
+* n'installe un protocole, on se sert d'un assistant — et c'est lui qui a besoin
+* de la porte. Une seule question, dans les mots de celui qui répond.
+*
+* Deux familles d'agents, une seule liste : ceux qui se déclarent par LEUR CLI
+* (`--agent <clés>`) et ceux qui lisent le `.mcp.json` du projet — pour ces
+* derniers, écrire le fichier EST la déclaration, d'où `none` plutôt que rien :
+* `--agent none` dit « n'appelle aucune CLI », pas « ne fais rien ».
+*
+* `--auth` : l'en-tête porte `${NF_MCP_TOKEN}`, jamais le jeton lui-même. Une
+* app neuve naît avec sa porte fermée ; l'ouvrir sans authentification serait un
+* défaut par défaut.
+*
+* @param chosen - clés cochées par l'utilisateur.
+* @param detected - agents présents sur ce poste (source unique `AGENT_TARGETS`).
+* @param dest - racine de l'app générée.
+* @returns l'argv à passer à `ai:mcp`, ou `null` quand aucun agent n'est choisi
+*   — coder seul est un choix, et rien ne doit alors être écrit.
+*/
+function argvMcpWiring(chosen, detected, dest) {
+	if (chosen.length === 0) return null;
+	const parCli = detected.filter((c) => c.declaration === "cli" && chosen.includes(c.key)).map((c) => c.key);
+	return [
+		"ai:mcp",
+		"--cwd",
+		dest,
+		"--auth",
+		"--agent",
+		parCli.length > 0 ? parCli.join(",") : "none"
+	];
+}
+/**
+* `git init` + first commit dans l'app générée — SEULEMENT si git est
+* disponible ET que le dossier n'est pas déjà couvert par un repo (une app de
+* banc dans le checkout du framework ne doit pas créer un repo imbriqué).
+* Le `.gitignore` généré exclut `*.local` AVANT ce commit : les secrets de
+* `.env.local` ne peuvent pas y entrer.
+*
+* `--git-hooks` : les hooks se posent ENTRE `git init` et le premier commit —
+* `.githooks/` entre ainsi dans le commit initial, comme les pointeurs de
+* skills. Une app déjà couverte par un repo (init sauté) les reçoit AUSSI :
+* `installGitHooks` calcule alors le chemin vu du toplevel, c'est son cas
+* monorepo. Le geste est celui de `nodefony git:hooks` — MÊME implémentation,
+* jamais recopiée.
+*
+* @returns note affichable (fait / sauté et pourquoi)
+*/
+function runGitInit(dest, appName, withHooks) {
+	const git = (...args) => spawnSync("git", args, {
+		cwd: dest,
+		stdio: "ignore"
+	});
+	const hooksNote = () => {
+		if (!withHooks) return "";
+		try {
+			const plan = installGitHooks(dest);
+			if (plan === null) return " · hooks non posés (hors dépôt git)";
+			return plan.refused ? " · hooks REFUSÉS (existant préservé — npx nodefony git:hooks pour le détail)" : ` · hooks natifs posés (${GIT_HOOKS_DIR}/ + core.hooksPath)`;
+		} catch (e) {
+			return ` · hooks non posés (${e.message})`;
+		}
+	};
+	if (spawnSync("git", ["--version"], { stdio: "ignore" }).error) return "git indisponible → repo non initialisé (git init à la main plus tard)";
+	if (git("rev-parse", "--is-inside-work-tree").status === 0) return `déjà dans un repo git → init sauté (pas de repo imbriqué)${hooksNote()}`;
+	if (git("init").status !== 0) return "git init a échoué → repo non initialisé";
+	const hooks = hooksNote();
+	git("add", "-A");
+	return (spawnSync("git", [
+		"commit",
+		"--no-verify",
+		"-m",
+		`chore: bootstrap ${appName} (nodefony create app)`
+	], {
+		cwd: dest,
+		stdio: "ignore"
+	}).status === 0 ? "repo git initialisé + premier commit" : "repo git initialisé (commit initial à faire : identité git non configurée ?)") + hooks;
+}
+/**
+* Commande `nodefony create` — orchestre l'adaptateur : parse argv, complète en
+* interactif si TTY, délègue au moteur, rend le récap.
+*
+* @returns exit code sémantique (`OK`, `USAGE`, `CANTCREAT`, `SOFTWARE`)
+*/
+async function runCreateCommand(argv) {
+	let parsed = parseCreateArgv(argv);
+	if ("error" in parsed && shouldAskForType(parsed.error, {
+		isTTY: process.stdin.isTTY === true,
+		yes: argv.includes("--yes")
+	})) {
+		const { select } = await chargePrompts();
+		const type = await select({
+			message: "Que veux-tu créer ?",
+			default: "app",
+			choices: CREATE_TYPES.map((t) => ({
+				name: `${t} — ${descriptionType(t)}`,
+				value: t
+			}))
+		});
+		const at = argv.indexOf("create");
+		const fullName = [...argv];
+		fullName.splice(at === -1 ? argv.length : at + 1, 0, type);
+		parsed = parseCreateArgv(fullName);
+	}
+	if ("error" in parsed) return printUsageError(PAGE, parsed.error);
+	if (parsed.help) return printUsage(PAGE);
+	if (parsed.describeJson) {
+		process.stdout.write(describeScaffold(parsed.type));
+		return 0;
+	}
+	const type = parsed.type;
+	const caps = { hasCheckout: resolveLocalWorkspaces(findPackageRoot()) !== null };
+	let answers = parsed.answers;
+	if (parsed.answersJson !== void 0) try {
+		answers = {
+			...readAnswersJson(parsed.answersJson, type),
+			...answers
+		};
+	} catch (e) {
+		process.stderr.write(`create: ${e.message}\n`);
+		return 64;
+	}
+	if (process.stdin.isTTY === true && !parsed.yes) {
+		const [spec] = getScaffoldSpec(type);
+		answers = await askMissing(spec, answers, caps, process.stdin, process.stdout, getScaffoldContext(process.cwd()));
+		const effective = new Map(spec.questions.map((q) => [q.key, answers[q.key] ?? q.default]));
+		const lines = spec.questions.filter((q) => !q.askWhen || String(effective.get(q.askWhen.key)) === q.askWhen.equals).map((q) => {
+			const value = answers[q.key] ?? q.default;
+			const shown = q.type === "boolean" ? value === true ? "oui" : "non" : String(value ?? "") || "(auto)";
+			return `  ${q.key.padEnd(10)} : ${shown}`;
+		}).join("\n");
+		process.stdout.write(`\nRécapitulatif :\n${lines}\n`);
+		if (!await confirm(parsed.dryRun ? "Simuler ?" : "Générer ?")) {
+			process.stdout.write("create: annulé\n");
+			return 0;
+		}
+	} else if (answers.link === void 0) answers.link = false;
+	if (answers.name === void 0 || answers.name === "") return printUsageError(PAGE, "nom requis");
+	const dir = parsed.dir ?? (type === "app" ? String(answers.name) : process.cwd());
+	let result;
+	try {
+		result = runScaffold({
+			type,
+			answers,
+			dir,
+			force: parsed.force
+		}, version, { dryRun: parsed.dryRun });
+	} catch (e) {
+		const message = e.message;
+		process.stderr.write(`create: ${message}\n`);
+		if (message.includes("n'est pas vide")) return 73;
+		if (message.includes("invalide")) return printUsageError(PAGE, message);
+		return 70;
+	}
+	const relDest = path.relative(process.cwd(), result.dest) || ".";
+	if (parsed.dryRun) {
+		process.stdout.write(`✔ ${type} « ${String(answers.name)} » — cible : ${relDest}/\n` + renderDryRun(result.changes ?? [], result.notes) + `\nRelance sans --dry-run pour écrire.\n`);
+		return 0;
+	}
+	if (type === "module") {
+		process.stdout.write(`✔ module « ${String(answers.name)} » généré dans ${relDest}/\n\n` + result.files.map((f) => `  ${f}`).join("\n") + `\n\nCâblage :\n` + (result.notes ?? []).map((n) => `  ${n}`).join("\n") + `\n`);
+		const projectRoot = findProjectRoot(process.cwd());
+		if (!parsed.install) {
+			const where = projectRoot ? path.relative(projectRoot, result.dest).split(path.sep).join("/") : String(answers.name);
+			process.stdout.write(`\nProchaines étapes (--no-install) :\n  npm install        # symlinke ${where} (workspace)\n  npm run build\n`);
+			return 0;
+		}
+		if (!(projectRoot !== null && runInstall(projectRoot)) || projectRoot === null) {
+			process.stdout.write(`⚠ npm install a échoué — relance-le à la racine de l'app (le module ne sera pas chargeable avant)\n`);
+			return 0;
+		}
+		runFormat(projectRoot, result.files);
+		const built = runBuild(projectRoot);
+		process.stdout.write(built ? `\n✔ module installé (workspace), module et application construits — un serveur dev le rechargera au prochain redémarrage\n` : `\n⚠ npm run build a échoué à la racine — corrige puis relance-le (le runtime charge le dist de l'app)\n`);
+		return 0;
+	}
+	if (type !== "app") {
+		const addedDeps = result.depsAdded ?? [];
+		if (parsed.install && addedDeps.length > 0) {
+			const root = findProjectRoot(process.cwd());
+			const pose = root !== null && runInstall(root);
+			process.stdout.write(pose ? `\n✔ dépendance(s) installée(s) : ${addedDeps.join(", ")}\n` : `\n⚠ npm install a échoué — relance-le à la racine du projet (${addedDeps.join(", ")} est déclaré mais absent de node_modules)\n`);
+		} else if (addedDeps.length > 0) process.stdout.write(`\n⚠ ${addedDeps.join(", ")} ajouté(s) au package.json et NON installé(s) (--no-install) → lance \`npm install\`\n`);
+		process.stdout.write(`✔ ${type} « ${String(answers.name)} » généré dans ${relDest}/\n\n` + result.files.map((f) => `  ${f}`).join("\n") + `\n\n${type === "command" ? "Câblage" : "Endpoints"} :\n` + (result.notes ?? []).map((n) => `  ${n}`).join("\n") + `\n\nServeur dev lancé → rebuild automatique ; sinon : npm run build\n`);
+		return 0;
+	}
+	const linkNote = result.linked.length ? `\n🔗 link : ${result.linked.length} paquets nodefony câblés en file: sur le checkout local (dev framework — ne pas publier ce package.json tel quel)\n` : "";
+	process.stdout.write(`✔ ${type} « ${String(answers.name)} » généré dans ${relDest}/\n\n` + result.files.map((f) => `  ${f}`).join("\n") + `\n${linkNote}`);
+	const installed = parsed.install ? runInstall(result.dest) : false;
+	if (parsed.install && !installed) process.stdout.write(`⚠ npm install a échoué — relance-le à la main dans ${relDest}/\n`);
+	if (installed) runFormat(result.dest, result.files);
+	const built = installed ? runBuild(result.dest) : false;
+	if (installed && !built) process.stdout.write(`⚠ npm run build a échoué — relance-le à la main dans ${relDest}/\n`);
+	let migrationWritten = false;
+	if (built) {
+		const migration = runInitialMigration(result.dest);
+		if (migration !== null) {
+			migrationWritten = migration.written;
+			process.stdout.write(`\n🗄️ migration initiale : ${migration.note}\n`);
+		}
+	}
+	process.stdout.write(`\n🤖 skills d'agent : ${poseSkillPointers(result.dest)}\n`);
+	const chosen = Array.isArray(answers.agents) ? answers.agents : [];
+	const wiring = mcpWiringPlan({
+		chosen: chosen.length,
+		installed,
+		built
+	});
+	let mcpNote = wiring.propose ? "" : wiring.pattern;
+	if (wiring.propose) {
+		const mcpCall = argvMcpWiring(chosen, AGENT_TARGETS, result.dest);
+		if (mcpCall === null) mcpNote = "aucun agent choisi";
+		else await runAiMcpCommand(mcpCall);
+	}
+	if (mcpNote !== "") process.stdout.write(`🔌 agents IA : ${mcpNote}\n`);
+	const gitNote = parsed.git ? runGitInit(result.dest, String(answers.name), answers.gitHooks === true) : "sauté (--no-git)";
+	process.stdout.write(`🌱 git : ${gitNote}\n`);
+	const needsInfra = answers.preset !== "minimal" && answers.database !== void 0 && answers.database !== "sqlite";
+	process.stdout.write(`\nProchaines étapes :\n  cd ${relDest}\n` + (installed ? "" : `  npm install\n`) + (built ? "" : `  npm run build\n`) + (needsInfra ? `  npm run infra:up   # docker : ${String(answers.database)} + Redis (NF_DATABASE_URL pointe dessus)\n` : "") + (!migrationWritten && appDeclareUnOrm(result.dest) ? `  npx nodefony orm:generate --name init   # écrit la migration de ta table User\n` : "") + `  npm run dev        # → https://127.0.0.1:5152 (ou le port libre suivant, annoncé au démarrage)\n` + (answers.preset === "complete" ? `                     # console d'administration : /nodefony — admin/admin en dev\n` : "") + (mcpNote !== "" ? `  npx nodefony ai:mcp # câbler ton agent IA (porte MCP + jeton)\n` : ""));
+	return createExitCode(parsed.install ? installed ? "succeeded" : "failed" : "skipped", installed ? built ? "succeeded" : "failed" : "skipped");
+}
+//#endregion
+export { CREATE_TYPES, argvMcpWiring, createExitCode, mcpWiringPlan, parseCreateArgv, renderDryRun, runCreateCommand, shouldAskForType };