nodefony 7.0.2 → 10.0.0-alpha.2

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

@@ -0,0 +1,704 @@
+import { AGENT_TARGETS } from "../agentTargets.js";
+//#region src/cli/scaffold/spec.ts
+/**
+* Spec DÉCLARATIVE du scaffold — la source unique des choix de création.
+*
+* Les questions sont des DONNÉES (JSON-able, zéro fonction) : le même contrat
+* alimente les TROIS fronts de création —
+*   1. CLI rapide     : flags argv → réponses (`--preset minimal --frontend react`) ;
+*   2. CLI interactif : `interactive.ts` rend chaque question en readline natif ;
+*   3. Studio         : un endpoint data plane sert `getScaffoldSpec()` en JSON,
+*      le formulaire React poste les réponses au MÊME moteur (`engine.ts`).
+*
+* ⚠️ **Deux fronts sur trois se servent seuls** : l'interactif et Studio LISENT
+* cette spec, donc une question ajoutée y apparaît sans qu'on les touche. La
+* voie FLAGS, elle, a une analyse écrite à la main (`parseCreateArgv`) : une
+* question sans drapeau est servie à l'humain et REFUSÉE au script, sans un mot
+* — c'est arrivé. Le drapeau se déduit de la clé (`maClé` → `--ma-cle`), sauf
+* mention `flag` ; et un test du dépôt refuse toute question qu'aucun drapeau
+* ne sert.
+*/
+/** Une question de scaffold — champ `pattern` en string (JSON-able, validation partagée). */
+/** Frameworks front supportés par `@nodefony/frontend` (builder Vite multi-framework). */
+const FRONTEND_CHOICES = [
+	"none",
+	"react",
+	"vue",
+	"angular",
+	"svelte"
+];
+/** Presets d'app : la vitrine complète (défaut) ou la base saine http+framework. */
+const PRESET_CHOICES = ["complete", "minimal"];
+/**
+* Base SQL de développement — le dialecte que l'app vise, choisi À LA CRÉATION.
+*
+* `sqlite` reste le défaut : c'est le seul qui n'exige aucun service, et la
+* promesse du framework est qu'une app fraîche démarre sans rien allumer. Les
+* trois autres ne changent RIEN dans le code de l'app (l'ORM déduit le dialecte
+* du scheme de `NF_DATABASE_URL`) — ils décident du service que l'infra de dev
+* fournit, et de l'URL qui la joint.
+*/
+const DATABASE_CHOICES = [
+	"sqlite",
+	"postgres",
+	"mariadb",
+	"mysql"
+];
+const APP_SPEC = {
+	type: "app",
+	description: "Application Nodefony autonome (hors du repo framework)",
+	questions: [
+		{
+			key: "name",
+			label: "Nom de l'application (kebab-case, ex : mon-app)",
+			type: "string",
+			default: "",
+			pattern: "^[a-z][a-z0-9-]*$",
+			patternHint: "kebab-case attendu — minuscules, chiffres, tirets (ex : mon-app)"
+		},
+		{
+			key: "preset",
+			label: "Contenu de l'application",
+			type: "choice",
+			choices: [{
+				value: "complete",
+				label: "Vitrine complète (recommandé)",
+				hint: "ORM + realtime + security + Studio + infra docker + tests e2e"
+			}, {
+				value: "minimal",
+				label: "Minimal",
+				hint: "http + framework seulement — la base saine, à faire grandir"
+			}],
+			default: "complete"
+		},
+		{
+			key: "database",
+			label: "Base SQL de développement",
+			type: "choice",
+			choices: [
+				{
+					value: "sqlite",
+					label: "sqlite (recommandé pour démarrer)",
+					hint: "aucun service à lancer — le fichier vit dans var/databases/"
+				},
+				{
+					value: "postgres",
+					label: "PostgreSQL 16",
+					hint: "service docker + NF_DATABASE_URL posée"
+				},
+				{
+					value: "mariadb",
+					label: "MariaDB 11.4",
+					hint: "fork libre de MySQL — même dialecte"
+				},
+				{
+					value: "mysql",
+					label: "MySQL 8.4",
+					hint: "service docker + NF_DATABASE_URL posée"
+				}
+			],
+			default: "sqlite",
+			askWhen: {
+				key: "preset",
+				equals: "complete"
+			}
+		},
+		{
+			key: "frontend",
+			label: "Framework frontend de l'app",
+			type: "choice",
+			choices: [
+				{
+					value: "none",
+					label: "Aucun",
+					hint: "API/backend seulement (ajoutable plus tard)"
+				},
+				{
+					value: "react",
+					label: "React 19",
+					hint: "entry Vite + HMR fast-refresh"
+				},
+				{
+					value: "vue",
+					label: "Vue 3",
+					hint: "SFC <script setup> + HMR"
+				},
+				{
+					value: "angular",
+					label: "Angular (standalone, zoneless)",
+					hint: "via AnalogJS"
+				},
+				{
+					value: "svelte",
+					label: "Svelte 5",
+					hint: "runes + HMR (plugin officiel)"
+				}
+			],
+			default: "none"
+		},
+		{
+			key: "link",
+			label: "Câbler les paquets nodefony sur le checkout local (dev framework) ?",
+			type: "boolean",
+			default: false,
+			askIf: "hasCheckout"
+		},
+		{
+			key: "gitHooks",
+			label: "Poser des hooks git natifs (typecheck+lint au commit) ?",
+			type: "boolean",
+			default: false,
+			advanced: true
+		},
+		{
+			key: "agents",
+			label: "Quel(s) agent(s) de développement utilises-tu ?",
+			type: "list",
+			choices: [{
+				value: "standard",
+				label: "Un autre agent, conforme aux standards ouverts",
+				hint: "AGENTS.md + MCP déposés dans le projet, aucune CLI lancée"
+			}, ...AGENT_TARGETS.map((target) => ({
+				value: target.key,
+				label: target.name,
+				hint: target.declaration === "cli" ? `configuré par sa CLI (\`${target.bin}\`)` : `se sert des fichiers du projet`
+			}))],
+			default: []
+		}
+	]
+};
+/** Saveurs de controller : le WS est TOUJOURS là (différenciateur Nodefony). */
+const CONTROLLER_KIND_CHOICES = [
+	"hello",
+	"rest",
+	"duplex",
+	"realtime",
+	"example"
+];
+const CONTROLLER_SPEC = {
+	type: "controller",
+	description: "Controller dans le projet courant (app racine ou module) — HTTP + WebSocket même classe",
+	questions: [
+		{
+			key: "name",
+			label: "Nom du controller (ex : blog ou BlogPost — suffixe Controller ajouté)",
+			type: "string",
+			default: "",
+			pattern: "^[A-Za-z][A-Za-z0-9-]*$",
+			patternHint: "lettres/chiffres/tirets, commence par une lettre (ex : blog, BlogPost)"
+		},
+		{
+			key: "kind",
+			label: "Saveur du controller",
+			type: "choice",
+			choices: [
+				{
+					value: "hello",
+					label: "HTTP + WebSocket (recommandé)",
+					hint: "pour DÉCOUVRIR le pipeline partagé : GET + echo WS même classe — WS métier → --kind realtime"
+				},
+				{
+					value: "rest",
+					label: "REST resource",
+					hint: "CRUD de production (list/get/create/update/delete) — HTTP pur"
+				},
+				{
+					value: "duplex",
+					label: "Duplex REST + socket (api.request)",
+					hint: "les MÊMES actions CRUD en HTTP ET par socket.request/mutate (@nodefony/realtime)"
+				},
+				{
+					value: "realtime",
+					label: "Realtime (socket Nodefony)",
+					hint: "canaux pub/sub + actions RPC via RealtimeController (@nodefony/realtime)"
+				},
+				{
+					value: "example",
+					label: "Vitrine des décorateurs",
+					hint: "démo pédagogique : TOUS les décorateurs commentés + curl d'essai"
+				}
+			],
+			default: "hello"
+		},
+		{
+			key: "route",
+			label: "Route de base (vide = /api/<nom> — couverte par la zone firewall ^/api)",
+			type: "string",
+			default: "",
+			pattern: "^$|^/[A-Za-z0-9/_-]*$",
+			patternHint: "chemin absolu (ex : /api/blog) ou vide pour le défaut"
+		},
+		{
+			key: "module",
+			label: "Cible (vide = app racine, sinon nom d'un module du projet)",
+			type: "string",
+			default: "",
+			pattern: "^$|^[@A-Za-z][@A-Za-z0-9/_-]*$",
+			patternHint: "nom d'un module du projet (dossier modules/<nom>) ou vide"
+		},
+		{
+			key: "role",
+			label: "Rôle exigé pour TOUT le controller (vide = aucune garde de rôle)",
+			type: "string",
+			default: "",
+			advanced: true,
+			pattern: "^$|^ROLE_[A-Z][A-Z0-9_]*$",
+			patternHint: "un rôle en capitales préfixé ROLE_ (ex : ROLE_BILLING) ou vide"
+		}
+	]
+};
+const SERVICE_SPEC = {
+	type: "service",
+	description: "Service injectable (@injectable) dans le projet courant (app racine ou module) — la logique métier, réutilisable par un controller, une commande CLI ou un autre module",
+	questions: [
+		{
+			key: "name",
+			label: "Nom du service (ex : billing ou Billing — suffixe Service ajouté)",
+			type: "string",
+			default: "",
+			pattern: "^[A-Za-z][A-Za-z0-9-]*$",
+			patternHint: "lettres/chiffres/tirets, commence par une lettre (ex : billing, UserBilling)"
+		},
+		{
+			key: "description",
+			label: "Description courte (TSDoc du service)",
+			type: "string",
+			default: ""
+		},
+		{
+			key: "inject",
+			label: "Injecter un service existant de la cible (nom de classe, ex : BillingService)",
+			type: "string",
+			default: "",
+			pattern: "^$|^[A-Za-z][A-Za-z0-9-]*$",
+			patternHint: "nom d'un service de la cible (nodefony/service/<Nom>Service.ts) ou vide"
+		},
+		{
+			key: "module",
+			label: "Cible (vide = app racine, sinon nom d'un module du projet)",
+			type: "string",
+			default: "",
+			pattern: "^$|^[@A-Za-z][@A-Za-z0-9/_-]*$",
+			patternHint: "nom d'un module du projet (dossier modules/<nom>) ou vide"
+		}
+	]
+};
+const FRONT_SPEC = {
+	type: "front",
+	description: "Ajoute un frontend Vite (page + entry + controller) à l'app ou à un module SANS front",
+	questions: [
+		{
+			key: "name",
+			label: "Nom de la page/entry (kebab-case, ex : dashboard)",
+			type: "string",
+			default: "",
+			pattern: "^[A-Za-z][A-Za-z0-9-]*$",
+			patternHint: "lettres/chiffres/tirets, commence par une lettre (ex : dashboard)"
+		},
+		{
+			key: "frontend",
+			label: "Framework frontend",
+			type: "choice",
+			choices: [
+				{
+					value: "react",
+					label: "React 19",
+					hint: "entry Vite + HMR fast-refresh"
+				},
+				{
+					value: "vue",
+					label: "Vue 3",
+					hint: "SFC <script setup> + HMR"
+				},
+				{
+					value: "angular",
+					label: "Angular (standalone, zoneless)",
+					hint: "via AnalogJS"
+				},
+				{
+					value: "svelte",
+					label: "Svelte 5",
+					hint: "runes + HMR (plugin officiel)"
+				}
+			],
+			default: "react"
+		},
+		{
+			key: "route",
+			label: "Route de la page (vide = /<nom>)",
+			type: "string",
+			default: "",
+			pattern: "^$|^/[A-Za-z0-9/_-]*$",
+			patternHint: "chemin absolu (ex : /dashboard) ou vide pour le défaut"
+		},
+		{
+			key: "module",
+			label: "Cible (vide = app racine, sinon nom d'un module du projet)",
+			type: "string",
+			default: "",
+			pattern: "^$|^[@A-Za-z][@A-Za-z0-9/_-]*$",
+			patternHint: "nom d'un module du projet (dossier modules/<nom>) ou vide"
+		}
+	]
+};
+/**
+* Saveurs de controller posables AVEC le module — les mêmes que `create
+* controller` (le scaffold module DÉLÈGUE, il ne duplique aucun template),
+* plus `none` pour une coquille nue.
+*/
+const MODULE_CONTROLLER_CHOICES = ["none", ...CONTROLLER_KIND_CHOICES];
+const MODULE_SPEC = {
+	type: "module",
+	description: "Module applicatif dans le projet courant (modules/<nom>/) — workspace npm, chargé par le manifeste",
+	questions: [
+		{
+			key: "name",
+			label: "Nom du module (kebab-case, ex : blog)",
+			type: "string",
+			default: "",
+			pattern: "^[a-z][a-z0-9-]*$",
+			patternHint: "kebab-case attendu — minuscules, chiffres, tirets (ex : blog, mon-module)"
+		},
+		{
+			key: "description",
+			label: "Description courte (README + docs + package.json)",
+			type: "string",
+			default: ""
+		},
+		{
+			key: "controller",
+			label: "Controller posé avec le module",
+			type: "choice",
+			choices: [
+				{
+					value: "hello",
+					label: "HTTP + WebSocket (recommandé)",
+					hint: "pour DÉCOUVRIR le pipeline partagé : GET + echo WS même classe — WS métier → --kind realtime"
+				},
+				{
+					value: "rest",
+					label: "REST resource",
+					hint: "CRUD de production (list/get/create/update/delete) — HTTP pur"
+				},
+				{
+					value: "duplex",
+					label: "Duplex REST + socket",
+					hint: "les MÊMES actions CRUD en HTTP ET par socket.request/mutate"
+				},
+				{
+					value: "realtime",
+					label: "Realtime (socket Nodefony)",
+					hint: "canaux pub/sub + actions RPC (@nodefony/realtime)"
+				},
+				{
+					value: "example",
+					label: "Vitrine des décorateurs",
+					hint: "démo pédagogique : TOUS les décorateurs commentés + curl d'essai"
+				},
+				{
+					value: "none",
+					label: "Aucun",
+					hint: "coquille nue — `nodefony create controller x --module <nom>` plus tard"
+				}
+			],
+			default: "hello"
+		},
+		{
+			key: "service",
+			label: "Service injectable principal (la logique du module) ?",
+			type: "boolean",
+			default: true
+		},
+		{
+			key: "command",
+			label: "Commande CLI (`nodefony <nom>:hello`) ?",
+			type: "boolean",
+			default: false
+		},
+		{
+			key: "frontend",
+			label: "Frontend Vite du module",
+			type: "choice",
+			choices: [
+				{
+					value: "none",
+					label: "Aucun",
+					hint: "backend seulement (ajoutable : `nodefony create front x --module <nom>`)"
+				},
+				{
+					value: "react",
+					label: "React 19",
+					hint: "entry Vite + HMR"
+				},
+				{
+					value: "vue",
+					label: "Vue 3",
+					hint: "SFC <script setup> + HMR"
+				},
+				{
+					value: "angular",
+					label: "Angular (standalone, zoneless)",
+					hint: "via AnalogJS"
+				}
+			],
+			default: "none"
+		}
+	]
+};
+/**
+* Phases de boot proposées comme point d'exécution d'une commande.
+*
+* C'est le `kernelEvent` de `OptionsCommandInterface` — le kernel s'ARRÊTE à
+* cette phase. Trois valeurs suffisent à couvrir les usages réels ; les autres
+* phases (`onPreBoot`, `onServersReady`…) restent atteignables en éditant le
+* fichier généré, mais n'ont pas à être proposées à qui crée sa première
+* commande.
+*/
+const COMMAND_PHASE_CHOICES = [
+	"onReady",
+	"onRegister",
+	"onPostReady"
+];
+const COMMAND_SPEC = {
+	type: "command",
+	description: "Commande CLI `nodefony <module>:<action>` dans le projet courant (app racine ou module)",
+	questions: [
+		{
+			key: "name",
+			label: "Action de la commande (ex : publish, user:add — le préfixe du module est ajouté)",
+			type: "string",
+			default: "",
+			pattern: "^[a-z][a-z0-9-]*(:[a-z][a-z0-9-]*)*$",
+			patternHint: "kebab-case, sous-actions séparées par « : » (ex : publish, user:add)"
+		},
+		{
+			key: "description",
+			label: "Description (affichée par `nodefony --help`)",
+			type: "string",
+			default: ""
+		},
+		{
+			key: "phase",
+			label: "Phase de boot où la commande s'exécute",
+			type: "choice",
+			choices: [
+				{
+					value: "onReady",
+					label: "Services prêts, aucun serveur (recommandé)",
+					hint: "lire/écrire des données, appeler un service — sans ouvrir de port"
+				},
+				{
+					value: "onRegister",
+					label: "Modules enregistrés",
+					hint: "ultra-léger : les services ne sont pas encore construits"
+				},
+				{
+					value: "onPostReady",
+					label: "Serveurs HTTP/WS en écoute",
+					hint: "seulement si la commande doit parler à ses propres serveurs"
+				}
+			],
+			default: "onReady"
+		},
+		{
+			key: "module",
+			label: "Cible (vide = app racine, sinon nom d'un module du projet)",
+			type: "string",
+			default: "",
+			pattern: "^$|^[@A-Za-z][@A-Za-z0-9/_-]*$",
+			patternHint: "nom d'un module du projet (dossier modules/<nom>) ou vide"
+		},
+		{
+			key: "service",
+			label: "Appeler le service du module (exemple de délégation)",
+			type: "boolean",
+			default: false,
+			advanced: true
+		},
+		{
+			key: "serviceName",
+			flag: "--service",
+			label: "Quel service appeler (vide = le seul de la cible)",
+			type: "string",
+			default: "",
+			advanced: true
+		}
+	]
+};
+/** Stratégies de clé primaire proposées par `create entity`. */
+const ENTITY_ID_CHOICES = [
+	"uuid7",
+	"uuid4",
+	"serial"
+];
+const SPECS = {
+	app: APP_SPEC,
+	module: MODULE_SPEC,
+	controller: CONTROLLER_SPEC,
+	service: SERVICE_SPEC,
+	front: FRONT_SPEC,
+	entity: {
+		type: "entity",
+		description: "Entité + schémas de validation + service CRUD + controller REST/WebSocket (dans l'app ou un module)",
+		questions: [
+			{
+				key: "name",
+				label: "Nom de l'entité (PascalCase, ex : Post)",
+				type: "string",
+				default: "",
+				pattern: "^[A-Za-z][A-Za-z0-9]*$",
+				patternHint: "PascalCase attendu — lettres et chiffres (ex : Post, BlogPost)"
+			},
+			{
+				key: "fields",
+				label: "Champs (nom:type, séparés par des espaces — ? nullable, ! unique, :index)",
+				type: "string",
+				default: ""
+			},
+			{
+				key: "id",
+				label: "Clé primaire",
+				type: "choice",
+				choices: [
+					{
+						value: "uuid7",
+						label: "UUID v7 (recommandé)",
+						hint: "ordonné dans le temps → index compact ; non énumérable"
+					},
+					{
+						value: "uuid4",
+						label: "UUID v4",
+						hint: "imprévisible — quand l'identifiant ne doit rien laisser deviner"
+					},
+					{
+						value: "serial",
+						label: "Auto-incrément",
+						hint: "table interne uniquement (un id exposé s'énumère)"
+					}
+				],
+				default: "uuid7"
+			},
+			{
+				key: "timestamps",
+				flag: "--no-timestamps",
+				label: "Horodatages createdAt / updatedAt",
+				type: "boolean",
+				default: true
+			},
+			{
+				key: "softDelete",
+				label: "Suppression douce (deletedAt)",
+				type: "boolean",
+				default: false
+			},
+			{
+				key: "controller",
+				label: "Controller REST + WebSocket",
+				type: "boolean",
+				default: true
+			},
+			{
+				key: "tests",
+				flag: "--no-tests",
+				label: "Tests (base sqlite en mémoire)",
+				type: "boolean",
+				default: true
+			},
+			{
+				key: "service",
+				label: "Service CRUD",
+				type: "boolean",
+				default: true,
+				advanced: true
+			},
+			{
+				key: "module",
+				label: "Module cible",
+				type: "string",
+				default: "",
+				advanced: true
+			},
+			{
+				key: "connector",
+				label: "Connecteur ORM",
+				type: "string",
+				default: "default",
+				advanced: true,
+				optionsFrom: "connectors"
+			},
+			{
+				key: "dialect",
+				label: "Dialecte SQL (défaut : lu dans la config)",
+				type: "string",
+				default: "",
+				advanced: true
+			},
+			{
+				key: "route",
+				label: "Route REST (défaut : /api/<pluriel>)",
+				type: "string",
+				default: "",
+				advanced: true
+			},
+			{
+				key: "table",
+				label: "Nom SQL de la table (défaut : pluriel du nom de l'entité)",
+				type: "string",
+				default: "",
+				advanced: true
+			},
+			{
+				key: "columnCase",
+				label: "Casse des colonnes SQL",
+				type: "choice",
+				choices: [{
+					value: "camel",
+					label: "camelCase",
+					hint: "la colonne porte le nom de la propriété (siteId)"
+				}, {
+					value: "snake",
+					label: "snake_case",
+					hint: "convention SQL courante (site_id) — la propriété reste siteId"
+				}],
+				default: "camel",
+				advanced: true
+			},
+			{
+				key: "idName",
+				label: "Nom SQL de la clé primaire (la propriété reste `id`)",
+				type: "string",
+				default: "id",
+				advanced: true
+			},
+			{
+				key: "index",
+				label: "Index de table, colonnes séparées par des virgules (ex. \"siteId,createdAt\")",
+				type: "list",
+				default: [],
+				advanced: true
+			},
+			{
+				key: "uniqueIndex",
+				flag: "--unique",
+				label: "Contrainte d'unicité sur plusieurs colonnes (ex. \"siteId,visitId\")",
+				type: "list",
+				default: [],
+				advanced: true
+			}
+		]
+	},
+	command: COMMAND_SPEC
+};
+/**
+* La spec complète du scaffold — contrat des trois fronts (CLI rapide,
+* CLI interactif, Studio). Structure 100 % sérialisable en JSON.
+*/
+function getScaffoldSpec(type) {
+	if (type) {
+		const spec = SPECS[type];
+		return spec ? [spec] : [];
+	}
+	return Object.values(SPECS);
+}
+//#endregion
+export { COMMAND_PHASE_CHOICES, CONTROLLER_KIND_CHOICES, DATABASE_CHOICES, ENTITY_ID_CHOICES, FRONTEND_CHOICES, MODULE_CONTROLLER_CHOICES, PRESET_CHOICES, getScaffoldSpec };