nodefony 7.0.2 → 10.0.0-alpha.2

package/dist/node/cli/cardReport.js

@@ -0,0 +1,110 @@
+//#region src/cli/cardReport.ts
+/**
+* Construit la carte de visite d'une application à partir de son état.
+*
+* Fonction **PURE** : elle reçoit l'état, elle ne le lit pas. C'est ce qui la
+* rend éprouvable sans Kernel ni serveur — et ce qui garantit qu'elle ne peut
+* rien inventer : tout ce qu'elle rend vient de ce qu'on lui a passé.
+*
+* ## Pourquoi les commandes portent `npx`
+*
+* Le binaire `nodefony` vit dans les `node_modules` de l'application : `nodefony`
+* nu rend 127. Mesuré sur agent réel — il recopie la FORME qu'on lui montre, pas
+* la règle écrite à côté. Une seule commande nue suffit à l'envoyer dans le mur
+* au premier geste.
+*
+* @param input - l'état de l'application (injecté, jamais lu ici).
+* @returns la carte, prête à rendre en texte ({@link renderCard}) ou en JSON.
+*/
+function buildCard(input) {
+	const modules = [...input.modules].sort();
+	const has = (name) => modules.includes(name);
+	const doors = [
+		{
+			title: "Les instructions de cette application",
+			where: "AGENTS.md",
+			why: "générateurs disponibles, table tâche → fichier, gates à passer. À lire AVANT d'écrire du code."
+		},
+		{
+			title: "Le catalogue des briques",
+			where: "node_modules/nodefony/docs/catalogue.md",
+			why: "quel module prendre pour quel besoin, et quand ne PAS le prendre."
+		},
+		{
+			title: "La documentation des modules installés",
+			where: "node_modules/@nodefony/*/docs/",
+			why: "elle est versionnée AVEC le code installé : elle ne peut pas décrire une autre version que la tienne."
+		}
+	];
+	if (has("studio")) doors.push({
+		title: "La console d'administration",
+		where: "/nodefony",
+		why: "l'application en marche : routes montées, services, config résolue, sessions, journaux."
+	});
+	if (has("documentation")) doors.push({
+		title: "L'index de documentation, en JSON",
+		where: "/nodefony/documentation/api/tree",
+		why: "la même documentation, lisible par un programme."
+	});
+	return {
+		app: {
+			name: input.appName,
+			version: input.appVersion,
+			environment: input.environment
+		},
+		nodefony: { version: input.nodefonyVersion },
+		modules,
+		source: input.source ?? "runtime",
+		doors,
+		verbs: [
+			{
+				command: "npx nodefony doctor",
+				why: "diagnostic STATIQUE : il ne lit que des fichiers, donc il répond même quand l'application ne démarre plus."
+			},
+			{
+				command: "npx nodefony inspect routes --json",
+				why: "ce qui est VRAIMENT monté, quand le code laisse croire autre chose. Sujets : routes, modules, services, config, stores, entities, graph."
+			},
+			{
+				command: "npx nodefony create entity Produit nom:string prix:float",
+				why: "l'entité, son service CRUD, son controller REST et ses tests. N'écris jamais à la main ce qu'un générateur produit."
+			},
+			{
+				command: "npm test",
+				why: "le premier diagnostic — avant de lire quoi que ce soit."
+			}
+		]
+	};
+}
+/**
+* Rend la carte pour un HUMAIN (ou un agent qui lit un terminal).
+*
+* PURE : elle ne touche ni au kernel ni au système de fichiers, donc elle
+* s'éprouve seule. Écrite sur `stdout` par ses appelants plutôt que par le
+* journal — une carte de visite n'est pas un événement de log, et le préfixe
+* horodaté rendrait le copier-coller inutilisable.
+*
+* La ligne des modules DIT sa provenance : « chargés » n'est vrai que si
+* l'application tournait au moment de la lecture. Sans cette mention, une carte
+* lue à froid ferait croire que le gating `policy`/`when` a déjà eu lieu.
+*
+* @param card - la carte composée par {@link buildCard}.
+* @returns le texte complet, prêt à écrire tel quel.
+*/
+function renderCard(card) {
+	const froid = card.source === "static";
+	return [
+		`${card.app.name} ${card.app.version} — ${card.app.environment} (nodefony ${card.nodefony.version})`,
+		"",
+		froid ? `Modules installés (${card.modules.length}) : ${card.modules.join(", ")}\n  ⓘ l'application n'a pas démarré — installés ≠ chargés. Ce qui est vraiment\n    monté : npx nodefony inspect modules` : `Modules chargés (${card.modules.length}) : ${card.modules.join(", ")}`,
+		"",
+		"Où aller :",
+		...card.doors.map((p) => `  ${p.where}\n      ${p.title} — ${p.why}`),
+		"",
+		"Quoi lancer :",
+		...card.verbs.map((v) => `  ${v.command}\n      ${v.why}`),
+		""
+	].join("\n");
+}
+//#endregion
+export { buildCard, renderCard };

package/dist/node/cli/completion.js

@@ -0,0 +1,415 @@
+import "./sysexits.js";
+import { OPTION_SUGGESTIONS } from "../command/Command.js";
+import { printUsage, printUsageError } from "./usageReport.js";
+import { mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync, writeSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { rename, writeFile } from "node:fs/promises";
+//#region src/cli/completion.ts
+/** Chemin du manifest cache — même dossier que le pidfile superviseur. */
+function cliManifestFile(cwd) {
+	return path.join(cwd, "node_modules", ".cache", "nodefony", "cli-manifest.json");
+}
+/** Extrait les flags candidats d'une chaîne commander (`"-w, --workers <number>"`). */
+function extractFlags(flags) {
+	return flags.split(/[\s,]+/).filter((t) => t.startsWith("-") && t !== "--");
+}
+/**
+* Les flags d'une commande qui attendent une valeur, et ce qu'on peut proposer.
+*
+* Deux sources, dans cet ordre : les `choices()` déclarés à commander (qui
+* VALIDENT, donc font autorité) et le registre des suggestions du produit (qui
+* ne valide rien, pour les options dont les valeurs sont ouvertes).
+*
+* @param cmd - la commande, telle que commander la porte.
+* @returns un tableau de valeurs par flag ; vide = valeur libre.
+*/
+function optionValuesOf(cmd) {
+	const out = {};
+	for (const o of cmd.options ?? []) {
+		if (!o.required && !o.optional) continue;
+		const values = [...o.argChoices ?? [], ...OPTION_SUGGESTIONS.get(o) ?? []];
+		for (const flag of extractFlags(o.flags)) out[flag] = values;
+	}
+	return out;
+}
+/**
+* Construit le manifest depuis l'état COURANT de commander — appelé après que les
+* modules ont posé leurs commandes (`onPreRegister`) pour un manifest complet, ou
+* avec les seuls built-ins pour le fallback sans boot.
+*/
+function buildCliManifest(commander, version) {
+	const commands = [];
+	for (const cmd of commander.commands) {
+		const name = cmd.name();
+		if (name.startsWith("__")) continue;
+		commands.push({
+			name,
+			aliases: cmd.aliases?.() ?? [],
+			description: cmd.description(),
+			options: (cmd.options ?? []).flatMap((o) => extractFlags(o.flags)),
+			args: (cmd.registeredArguments ?? []).map((a) => a.argChoices ?? []),
+			optionValues: optionValuesOf(cmd),
+			...typeof cmd.helpGroup?.() === "string" ? { group: cmd.helpGroup() } : {}
+		});
+	}
+	return {
+		version,
+		globalOptions: (commander.options ?? []).flatMap((o) => extractFlags(o.flags)),
+		commands
+	};
+}
+/**
+* Écrit le manifest cache (mkdir -p + write async). Best-effort : l'appelant décide
+* du fire-and-forget — un échec (FS read-only, pas de node_modules) ne doit JAMAIS
+* impacter le boot.
+*/
+async function writeCliManifest(commander, cwd, version) {
+	const file = cliManifestFile(cwd);
+	mkdirSync(path.dirname(file), { recursive: true });
+	const manifest = buildCliManifest(commander, version);
+	cleanOrphanTempFiles(file);
+	const tmp = `${file}.${process.pid}.tmp`;
+	try {
+		await writeFile(tmp, JSON.stringify(manifest, null, 1), "utf8");
+		await rename(tmp, file);
+	} catch (e) {
+		try {
+			rmSync(tmp, { force: true });
+		} catch {}
+		throw e;
+	}
+}
+/**
+* Efface les temporaires d'écriture dont le process propriétaire est mort.
+*
+* Best-effort de bout en bout : un dossier illisible, un fichier déjà repris
+* par quelqu'un d'autre, une permission refusée — rien de tout cela ne doit
+* empêcher d'écrire le manifest, qui est le vrai travail.
+*
+* @param file - chemin du manifest ; ses temporaires en dérivent
+*/
+function cleanOrphanTempFiles(file) {
+	try {
+		const folder = path.dirname(file);
+		const base = `${path.basename(file)}.`;
+		for (const input of readdirSync(folder)) {
+			if (!input.startsWith(base) || !input.endsWith(".tmp")) continue;
+			const pid = Number.parseInt(input.slice(base.length, -4), 10);
+			if (!Number.isInteger(pid) || pid <= 0) continue;
+			if (pid === process.pid) continue;
+			try {
+				process.kill(pid, 0);
+				continue;
+			} catch {}
+			rmSync(path.join(folder, input), { force: true });
+		}
+	} catch {}
+}
+/** Lit le manifest cache — `null` si absent ou corrompu (jamais de throw). */
+function readCliManifest(cwd) {
+	try {
+		const raw = readFileSync(cliManifestFile(cwd), "utf8");
+		const parsed = JSON.parse(raw);
+		return Array.isArray(parsed.commands) ? parsed : null;
+	} catch {
+		return null;
+	}
+}
+/**
+* Calcule les candidats de complétion pour les mots tapés.
+*
+* Protocole : `words` = tous les mots APRÈS le nom du binaire, dernier mot inclus
+* même vide (les scripts shell le transmettent tel quel). Le DERNIER mot est celui
+* en cours de frappe → la sélection de commande ne regarde que les mots VALIDÉS
+* (`slice(0, -1)`), et le shell filtre les candidats par le préfixe courant.
+*
+* - commande déjà validée → les CHOIX de l'argument positionnel en cours (s'il
+*   en déclare, ex. `create` → `app`) + ses options + les options globales ;
+* - sinon → noms + alias de toutes les commandes.
+*/
+function computeCompletions(manifest, words) {
+	const validated = words.slice(0, -1);
+	for (let i = 0; i < validated.length; i++) {
+		const w = validated[i];
+		if (w.startsWith("-")) continue;
+		const cmd = manifest.commands.find((c) => c.name === w || c.aliases.includes(w));
+		if (cmd) {
+			const after = validated.slice(i + 1);
+			let pos = 0;
+			for (let j = 0; j < after.length; j++) {
+				if (after[j].startsWith("-")) continue;
+				if (j > 0 && after[j - 1].startsWith("-")) continue;
+				pos++;
+			}
+			const last = validated[validated.length - 1] ?? "";
+			const expected = cmd.optionValues?.[last];
+			if (expected) return expected;
+			return [
+				...cmd.args?.[pos] ?? [],
+				...cmd.options,
+				...manifest.globalOptions
+			];
+		}
+	}
+	return manifest.commands.flatMap((c) => [c.name, ...c.aliases]);
+}
+/** Shells supportés par `nodefony completion <shell>`. */
+const COMPLETION_SHELLS = [
+	"bash",
+	"zsh",
+	"fish"
+];
+/** La page d'aide — `nodefony completion --help`, et le rappel après un refus. */
+const PAGE = {
+	command: "nodefony completion",
+	tagline: "le script de complétion à sourcer, ou son installation dans le fichier de démarrage du shell",
+	synopsis: [`nodefony completion [${COMPLETION_SHELLS.join("|")}]`, `nodefony completion install|uninstall [${COMPLETION_SHELLS.join("|")}]`],
+	sections: [{
+		title: "CE QU'ELLE FAIT",
+		paragraph: "Sans action, elle IMPRIME le script — à rediriger soi-même. Avec `install`, elle l'écrit et pose un bloc marqué, idempotent, dans le fichier de démarrage du shell ; `uninstall` le retire. Le script est STABLE : il délègue tout au binaire, donc les commandes qu'un module ajoute apparaissent sans jamais le régénérer. Sans shell nommé, celui de l'environnement est détecté."
+	}],
+	options: [],
+	examples: [
+		{
+			term: "nodefony completion zsh",
+			text: "imprime le script — à rediriger où le shell le lira"
+		},
+		{
+			term: "nodefony completion install",
+			text: "l'installe pour le shell détecté"
+		},
+		{
+			term: "nodefony completion uninstall bash",
+			text: "retire le bloc posé dans le fichier de démarrage"
+		}
+	]
+};
+/**
+* Rend le script de complétion à sourcer pour un shell. Le script est STABLE (il
+* délègue tout au binaire via `__complete`) : les commandes de module apparaissent
+* sans jamais regénérer le script — seule la donnée (manifest cache) bouge.
+*/
+function renderCompletionScript(shell) {
+	switch (shell) {
+		case "zsh": return `#compdef nodefony
+# Complétion zsh Nodefony — installation :
+#   nodefony completion zsh > "\${fpath[1]}/_nodefony"   (puis: exec zsh)
+# ou directe dans ~/.zshrc :
+#   source <(nodefony completion zsh)
+# ⚠️ La complétion s'applique au MOT \`nodefony\` en 1ʳᵉ position — PAS à
+# \`npx nodefony\` (le shell complète alors npx). Pour un usage projet :
+#   export PATH="$PWD/node_modules/.bin:$PATH"
+# Le système de complétion doit être chargé (compdef) — auto-init sinon.
+if ! whence compdef >/dev/null 2>&1; then
+  autoload -Uz compinit && compinit
+fi
+_nodefony_bin() {
+  if [ -x ./node_modules/.bin/nodefony ]; then
+    echo ./node_modules/.bin/nodefony
+  elif command -v nodefony >/dev/null 2>&1; then
+    echo nodefony
+  else
+    echo npx --no-install nodefony
+  fi
+}
+_nodefony() {
+  local -a candidates
+  # \${words[@]:1} : tous les mots APRÈS le nom du binaire, mot en frappe inclus
+  # (offset d'expansion 0-based — :1 saute uniquement "nodefony").
+  candidates=("\${(@f)$(\${=$(_nodefony_bin)} __complete -- "\${words[@]:1}" 2>/dev/null)}")
+  (( \${#candidates} )) && compadd -a candidates
+}
+compdef _nodefony nodefony
+`;
+		case "bash": return `# Complétion bash Nodefony — installation :
+#   nodefony completion bash > /etc/bash_completion.d/nodefony
+# ou directe dans ~/.bashrc :
+#   source <(nodefony completion bash)
+# ⚠️ S'applique au MOT \`nodefony\` en 1ʳᵉ position — PAS à \`npx nodefony\`.
+# Usage projet : export PATH="$PWD/node_modules/.bin:$PATH"
+_nodefony_bin() {
+  if [ -x ./node_modules/.bin/nodefony ]; then
+    echo ./node_modules/.bin/nodefony
+  elif command -v nodefony >/dev/null 2>&1; then
+    echo nodefony
+  else
+    echo npx --no-install nodefony
+  fi
+}
+_nodefony_completions() {
+  local cur="\${COMP_WORDS[COMP_CWORD]}"
+  local candidates
+  candidates="$($(_nodefony_bin) __complete -- "\${COMP_WORDS[@]:1}" 2>/dev/null)"
+  COMPREPLY=($(compgen -W "$candidates" -- "$cur"))
+}
+complete -F _nodefony_completions nodefony
+`;
+		case "fish": return `# Complétion fish Nodefony — installation :
+#   nodefony completion fish > ~/.config/fish/completions/nodefony.fish
+function __nodefony_bin
+  if test -x ./node_modules/.bin/nodefony
+    echo ./node_modules/.bin/nodefony
+  else if command -sq nodefony
+    echo nodefony
+  else
+    echo npx --no-install nodefony
+  end
+end
+complete -c nodefony -f -a "(eval (__nodefony_bin) __complete -- (commandline -opc)[2..-1] 2>/dev/null)"
+`;
+	}
+}
+/** Détecte le shell courant depuis `$SHELL` (fallback interactif du sous-commande nu). */
+function detectShell() {
+	const sh = path.basename(process.env.SHELL ?? "");
+	return COMPLETION_SHELLS.includes(sh) ? sh : null;
+}
+const BLOCK_BEGIN = "# >>> nodefony completion >>>";
+const BLOCK_END = "# <<< nodefony completion <<<";
+/** Cibles d'installation d'un shell : fichier script + rc à marquer (`null` = aucun). */
+function completionInstallTargets(shell, home) {
+	switch (shell) {
+		case "zsh": return {
+			scriptFile: path.join(home, ".config", "nodefony", "completion.zsh"),
+			rcFile: path.join(home, ".zshrc")
+		};
+		case "bash": return {
+			scriptFile: path.join(home, ".config", "nodefony", "completion.bash"),
+			rcFile: path.join(home, ".bashrc")
+		};
+		case "fish": return {
+			scriptFile: path.join(home, ".config", "fish", "completions", "nodefony.fish"),
+			rcFile: null
+		};
+	}
+}
+/** Retire le bloc marqué (avec ses marqueurs) d'un contenu rc — no-op si absent. */
+function removeBlock(content) {
+	const begin = content.indexOf(BLOCK_BEGIN);
+	if (begin < 0) return content;
+	const end = content.indexOf(BLOCK_END, begin);
+	if (end < 0) return content;
+	const after = end + 29;
+	const head = content.slice(0, begin).replace(/\n+$/, "");
+	const tail = content.slice(after).replace(/^\n+/, "");
+	if (head.length === 0) return tail;
+	return tail.length > 0 ? `${head}\n${tail}` : `${head}\n`;
+}
+/** Insère (ou remplace) le bloc marqué sourçant `scriptFile` — idempotent. */
+function upsertBlock(content, scriptFile) {
+	const cleaned = removeBlock(content).replace(/\n+$/, "");
+	const block = `${BLOCK_BEGIN}\n[ -f "${scriptFile}" ] && source "${scriptFile}"\n${BLOCK_END}\n`;
+	return cleaned.length > 0 ? `${cleaned}\n\n${block}` : block;
+}
+/**
+* Installe la complétion pour un shell : écrit le script (mkdir -p) et, si le shell
+* en a besoin, upsert le bloc marqué dans son rc (créé s'il n'existe pas).
+*
+* @returns les chemins touchés (pour le rapport utilisateur).
+*/
+function installCompletion(shell, home) {
+	const targets = completionInstallTargets(shell, home);
+	mkdirSync(path.dirname(targets.scriptFile), { recursive: true });
+	writeFileSync(targets.scriptFile, renderCompletionScript(shell), "utf8");
+	if (targets.rcFile) {
+		let rc = "";
+		try {
+			rc = readFileSync(targets.rcFile, "utf8");
+		} catch {}
+		writeFileSync(targets.rcFile, upsertBlock(rc, targets.scriptFile), "utf8");
+	}
+	return targets;
+}
+/** Désinstalle : retire le bloc du rc et supprime le fichier script. */
+function uninstallCompletion(shell, home) {
+	const targets = completionInstallTargets(shell, home);
+	rmSync(targets.scriptFile, { force: true });
+	if (targets.rcFile) try {
+		const rc = readFileSync(targets.rcFile, "utf8");
+		writeFileSync(targets.rcFile, removeBlock(rc), "utf8");
+	} catch {}
+	return targets;
+}
+/** Consigne de rechargement par shell (affichée après install). */
+function reloadHint(shell) {
+	if (shell === "fish") return "ouvre un nouveau shell fish";
+	return `exec ${shell}`;
+}
+/**
+* Fast-path `nodefony completion [install|uninstall] [shell]` — imprime le script,
+* ou l'installe/désinstalle dans le rc du shell (bloc marqué idempotent).
+*
+* @returns exit code (`EX_OK`, ou `EX_USAGE` si shell inconnu et indétectable).
+*/
+function runCompletionCommand(argv) {
+	const at = argv.indexOf("completion");
+	if (at !== -1 && argv.slice(at + 1).some((a) => a === "--help" || a === "-h")) return printUsage(PAGE);
+	const positionals = argv.slice(2).filter((a) => !a.startsWith("-"));
+	const action = positionals[1] === "install" || positionals[1] === "uninstall" ? positionals[1] : null;
+	const arg = positionals[action ? 2 : 1];
+	const shell = arg && COMPLETION_SHELLS.includes(arg) ? arg : detectShell();
+	if (!shell || arg && !COMPLETION_SHELLS.includes(arg)) return printUsageError(PAGE, arg ? `shell inconnu : ${arg}` : "shell indétectable — nommez-le (ex. nodefony completion zsh)");
+	const home = os.homedir();
+	if (action === "install") {
+		const { scriptFile, rcFile } = installCompletion(shell, home);
+		writeSync(1, `✓ script  : ${scriptFile}\n`);
+		if (rcFile) writeSync(1, `✓ rc      : ${rcFile} (bloc « nodefony completion », idempotent)\n`);
+		writeSync(1, `→ recharge : ${reloadHint(shell)}\n→ retirer  : nodefony completion uninstall ${shell}\n⚠️ complète \`nodefony …\` (pas \`npx nodefony\`) — usage projet :\n   export PATH="$PWD/node_modules/.bin:$PATH"\n`);
+		return 0;
+	}
+	if (action === "uninstall") {
+		const { scriptFile, rcFile } = uninstallCompletion(shell, home);
+		writeSync(1, `✓ retiré : ${scriptFile}\n`);
+		if (rcFile) writeSync(1, `✓ rc     : ${rcFile} (bloc retiré)\n`);
+		return 0;
+	}
+	writeSync(1, renderCompletionScript(shell));
+	return 0;
+}
+/**
+* Fusionne les commandes du **code courant** (built-ins, construits en mémoire) avec
+* celles que seul le manifest cache connaît (les commandes de MODULE, posées à
+* `onPreRegister` — impossible de les lister sans booter).
+*
+* Pourquoi cette asymétrie : le cache est écrit au boot dev et n'est jamais invalidé
+* (sa clé est la version du paquet, identique d'un build à l'autre en développement).
+* S'il faisait autorité sur les built-ins, la complétion resterait figée sur l'état du
+* dernier boot — un `create` enrichi d'un nouveau type ne le proposerait jamais (vécu).
+* Le binaire, lui, est toujours à jour par construction : il EST le code courant.
+*
+* Un module retiré peut donc survivre dans la liste jusqu'au prochain boot dev — un
+* candidat en trop au TAB, sans conséquence, corrigé au boot suivant.
+*/
+function mergeManifests(builtins, cached) {
+	if (!cached) return builtins;
+	const known = /* @__PURE__ */ new Set();
+	for (const c of builtins.commands) {
+		known.add(c.name);
+		for (const a of c.aliases) known.add(a);
+	}
+	const moduleCommands = cached.commands.filter((c) => !known.has(c.name));
+	return {
+		...builtins,
+		commands: [...builtins.commands, ...moduleCommands]
+	};
+}
+/**
+* Fast-path `nodefony __complete -- <mots>` — imprime un candidat par ligne.
+*
+* Source : built-ins du binaire courant (`builtins`, construits en mémoire par le
+* CliKernel, sans boot) + commandes de module lues dans le manifest cache. Sort
+* TOUJOURS `EX_OK` : le pire résultat d'une complétion est une liste vide, jamais une
+* erreur dans le TAB.
+*/
+function runCompleteQuery(argv, builtins) {
+	try {
+		const sep = argv.indexOf("--");
+		const words = sep >= 0 ? argv.slice(sep + 1) : [];
+		const candidates = computeCompletions(mergeManifests(builtins(), readCliManifest(process.cwd())), words);
+		if (candidates.length > 0) writeSync(1, candidates.join("\n") + "\n");
+	} catch {}
+	return 0;
+}
+//#endregion
+export { COMPLETION_SHELLS, buildCliManifest, cliManifestFile, completionInstallTargets, computeCompletions, detectShell, extractFlags, installCompletion, mergeManifests, readCliManifest, removeBlock, renderCompletionScript, runCompleteQuery, runCompletionCommand, uninstallCompletion, upsertBlock, writeCliManifest };