nodefony 7.0.2 → 10.0.0-alpha.2

package/dist/node/cli/manPage.js

@@ -0,0 +1,165 @@
+import { groupCommands } from "./helpReport.js";
+import { Buffer } from "node:buffer";
+//#region src/cli/manPage.ts
+/**
+* Page de manuel Unix (`man nodefony`), rendue depuis le manifest du CLI.
+*
+* **Pourquoi générer plutôt qu'écrire.** Une page man est un fichier statique
+* installé avec le paquet ; écrite à la main, elle diverge du CLI au premier
+* ajout de commande, et personne ne s'en aperçoit — c'est précisément ce que la
+* règle « la documentation décrit la vérité COURANTE » interdit. Le manifest
+* ({@link ICliManifest}) est extrait de commander, donc de la même source que
+* `--help` et que la complétion : cette page en est la TROISIÈME porte, avec la
+* même garantie de fraîcheur. Un gate compare la page committée à cette sortie.
+*
+* **Ce que la page NE PEUT PAS contenir, et qu'elle doit donc annoncer.** Douze
+* des commandes du CLI viennent des MODULES de l'application (`http:network`,
+* `frontend:build`, `security:user:add`…) : elles dépendent du projet dans
+* lequel on se trouve, quand la page est installée une fois pour toutes avec le
+* paquet. Elle documente donc les commandes du FRAMEWORK et renvoie
+* explicitement à `nodefony --help` pour les autres — une page qui énonce sa
+* propre frontière, plutôt qu'une page qui laisse croire qu'elle liste tout.
+*
+* **Aucune date.** `.TH` accepte un champ date ; le remplir rendrait la sortie
+* non déterministe et ferait échouer le gate le lendemain de sa génération. La
+* version tient ce rôle, et c'est la seule chose qu'on veuille y lire.
+*
+* **Portabilité.** `man` existe sous Linux et macOS ; npm installe la page à
+* l'installation GLOBALE. Windows n'a pas de `man` natif et npm y ignore le
+* champ : `nodefony --help` y reste la porte, et la page ne prétend rien
+* d'autre.
+*/
+/**
+* Largeur des lignes du SOURCE, en octets.
+*
+* 78 et non 80 : deux octets de marge coûtent moins qu'un avertissement
+* récurrent qu'on apprendrait à ignorer.
+*
+* ⚠️ **`mandoc -T lint` en signalera QUAND MÊME quelques-unes, et c'est un
+* artefact de sa mesure, pas un défaut de la page.** Il normalise chaque
+* caractère non-ASCII en séquence d'échappement avant de compter — un `é`
+* devient `\[u00E9]`, soit 9 octets au lieu de 2 — si bien qu'une page en
+* français dépasse toujours son seuil. Ces avertissements sont de niveau STYLE
+* et n'ont aucun effet sur le rendu (vérifié : `man` affiche la page
+* correctement). Ne PAS en faire un gate : il faudrait mutiler les
+* paragraphes pour satisfaire une mesure qui ne décrit pas le fichier réel.
+*/
+const MAN_SOURCE_WIDTH = 78;
+/** Nom de la page, section 1 (commandes utilisateur). */
+const MAN_PAGE_NAME = "nodefony.1";
+/**
+* Échappe une chaîne pour roff.
+*
+* Trois pièges, tous silencieux — ils ne produisent pas d'erreur, seulement une
+* page mal rendue : la contre-oblique introduit les séquences roff, le tiret nu
+* devient un tiret TYPOGRAPHIQUE (illisible dans une option `--json`, et non
+* copiable), et une ligne qui COMMENCE par un point ou une apostrophe est lue
+* comme une directive.
+*/
+function escapeRoff(text) {
+	const escaped = text.replace(/\\/gu, "\\\\").replace(/-/gu, "\\-").trim().replace(/[^\S\n]*\n\s*/gu, " ");
+	return /^[.']/u.test(escaped) ? `\\&${escaped}` : escaped;
+}
+/**
+* Replie une ligne de TEXTE à 80 colonnes, sur les espaces.
+*
+* Convention des sources man, et pas seulement de la coquetterie : `mandoc -T
+* lint` la contrôle, si bien qu'une source non repliée noie ses propres
+* avertissements sous des dizaines de « line longer than 80 bytes » — on ne
+* verrait plus passer une vraie erreur de structure. Le rendu, lui, ne change
+* pas : roff recompose les paragraphes.
+*
+* Les DIRECTIVES (`.TH`, `.TP`, `.B …`) ne sont jamais repliées — une ligne de
+* directive coupée en deux cesse d'être une directive.
+*
+* ⚠️ **La limite est en OCTETS, pas en caractères** : c'est ainsi que `mandoc`
+* compte, et cette page est en français. Replier sur `String.length` laissait
+* passer toute ligne accentuée — un `é` pèse deux octets, donc une ligne de 79
+* caractères pouvait en faire 90.
+*/
+function wrap(line) {
+	const byteLength = (s) => Buffer.byteLength(s, "utf8");
+	if (line.startsWith(".") || byteLength(line) <= MAN_SOURCE_WIDTH) return line;
+	const out = [];
+	let current = "";
+	for (const word of line.split(" ")) if (current && byteLength(`${current} ${word}`) > MAN_SOURCE_WIDTH) {
+		out.push(current);
+		current = word;
+	} else current = current ? `${current} ${word}` : word;
+	if (current) out.push(current);
+	return out.join("\n");
+}
+/** Une entrée de liste `.TP` : un terme en gras, sa description en dessous. */
+function tagged(term, description) {
+	return `.TP\n.B ${term}\n${escapeRoff(description) || "\\-"}`;
+}
+/**
+* Rend la page de manuel complète, en roff.
+*
+* @param manifest - le manifest des commandes INTÉGRÉES (extrait de commander).
+* @param version - version du paquet, affichée dans l'en-tête et le pied.
+* @returns le source roff, terminé par un saut de ligne.
+*/
+function renderManPage(manifest, version) {
+	const out = [];
+	const v = escapeRoff(version);
+	out.push(`.TH NODEFONY 1 "" "nodefony ${v}" "Nodefony Manual"`);
+	out.push(".SH NAME");
+	out.push("nodefony \\- framework fullstack Node.js : HTTP, WebSocket, ORM, agents");
+	out.push(".SH SYNOPSIS");
+	out.push(".B nodefony");
+	out.push("[\\fICOMMANDE\\fR] [\\fIOPTIONS\\fR]");
+	out.push(".br");
+	out.push(".B nodefony");
+	out.push("\\fB\\-\\-help\\fR | \\fB\\-\\-version\\fR");
+	out.push(".SH DESCRIPTION");
+	out.push("Interface en ligne de commande de Nodefony : elle lance l'application (développement, production, cluster), la construit, l'inspecte et la diagnostique, et engendre du code conforme au framework.");
+	out.push(".PP");
+	out.push("Lancée sans argument dans un terminal interactif, elle ouvre un menu des gestes utiles ici. Hors terminal, elle affiche l'aide.");
+	out.push(".PP");
+	out.push("\\fBCette page ne liste que les commandes du FRAMEWORK.\\fR Une application en ajoute par ses modules \\- par exemple \\fBhttp:network\\fR, \\fBfrontend:build\\fR ou \\fBsecurity:user:add\\fR \\- et celles\\-ci dépendent du projet dans lequel la commande est lancée. Pour la liste RÉELLE, dans le projet courant :");
+	out.push(".PP");
+	out.push(".RS 4");
+	out.push(".B nodefony \\-\\-help");
+	out.push(".RE");
+	out.push(".SH COMMANDS");
+	out.push("Les commandes sont rangées par INTENTION, dans l'ordre d'une journée de travail \\- comme \\fBnodefony \\-\\-help\\fR. Un rangement alphabétique mettrait \\fBai:mcp\\fR avant \\fBdevelopment\\fR ; il ne répond à personne.");
+	for (const group of groupCommands(manifest.commands.map((c) => ({
+		name: c.name,
+		aliases: c.aliases ?? [],
+		description: c.description,
+		...c.group === void 0 ? {} : { group: c.group }
+	})))) {
+		out.push(`.SS ${escapeRoff(group.title)}`);
+		for (const cmd of group.commands) out.push(tagged([cmd.name, ...cmd.aliases].map((n) => escapeRoff(n)).join(", "), cmd.description));
+	}
+	if (manifest.globalOptions.length > 0) {
+		out.push(".SH OPTIONS");
+		out.push("Options acceptées par toutes les commandes. Chaque commande porte en plus les siennes, que \\fBnodefony \\fI<commande>\\fB \\-\\-help\\fR détaille.");
+		for (const opt of manifest.globalOptions) {
+			out.push(".TP");
+			out.push(`.B ${escapeRoff(opt)}`);
+		}
+	}
+	out.push(".SH ENVIRONMENT");
+	out.push(tagged("NODE_ENV", "Mode d'exécution (development | production). Posé par l'orchestrateur, il PRIME sur l'intention de la commande."));
+	out.push(tagged("APP_ENV", "Environnement de DÉPLOIEMENT, libre (staging, canary, prod-eu). Axe distinct du mode d'exécution."));
+	out.push(tagged("NF_*", "Toute variable lue par Nodefony porte ce préfixe. nodefony env en dresse la cascade et la provenance."));
+	out.push(tagged("NF__<MODULE>__<CHEMIN>", "Surcharge une clé de configuration d'un module (double souligné entre les niveaux), appliquée avant la validation du schéma."));
+	out.push(".SH FILES");
+	out.push(tagged("nodefony.config.ts", "Configuration de l'application. Sa présence marque la racine du projet."));
+	out.push(tagged("env.ts", "Catalogue des variables d'environnement de l'application."));
+	out.push(tagged("node_modules/.cache/nodefony/cli\\-manifest.json", "Cache des commandes, réécrit à chaque commande. Sert la complétion et le menu, qui doivent répondre sans démarrer l'application."));
+	out.push(".SH EXAMPLES");
+	out.push(tagged("nodefony create app mon\\-app", "Crée une application."));
+	out.push(tagged("nodefony dev", "Démarre en développement, avec redémarrage à chaud."));
+	out.push(tagged("nodefony inspect routes", "Affiche les routes RÉELLEMENT montées, sans ouvrir de port."));
+	out.push(tagged("nodefony doctor", "Diagnostique le projet, même s'il ne démarre plus."));
+	out.push(".SH SEE ALSO");
+	out.push("La documentation complète vit dans le projet (\\fBdocs/\\fR) et dans la console d'administration. \\fBnodefony card\\fR rend la carte de visite de l'application : où aller, quoi lancer.");
+	out.push(".SH AUTHOR");
+	out.push("Christophe CAMENSULI et les contributeurs de Nodefony.");
+	return `${out.join("\n").split("\n").map(wrap).join("\n")}\n`;
+}
+//#endregion
+export { MAN_PAGE_NAME, escapeRoff, renderManPage };

package/dist/node/cli/nodefonyBin.js

@@ -0,0 +1,61 @@
+import { createRequire } from "node:module";
+import path from "node:path";
+//#region src/cli/nodefonyBin.ts
+/**
+* Le chemin du lanceur `nodefony`, tel que CETTE installation l'a reçu.
+*
+* ## Pourquoi une fonction, et pas un chemin écrit à la main
+*
+* Un appelant qui doit démarrer l'application — une suite de tests, un shim de
+* création d'application, un script de déploiement — écrivait jusqu'ici
+* `node_modules/.bin/nodefony`. Trois choses lui donnent tort :
+*
+*  1. **Ce fichier n'existe pas sous Windows.** npm y écrit un `nodefony.cmd`,
+*     et Node refuse d'exécuter un script batch sans passer par un shell
+*     (correctif de CVE-2024-27980). Le symptôme est un `ENOENT` sur un chemin
+*     qui semble pourtant présent — il désigne le fichier SANS extension.
+*  2. **L'emplacement n'est pas garanti.** Hoisting npm, espaces de travail,
+*     pnpm et son magasin : le paquet n'est pas toujours dans le
+*     `node_modules` du dossier courant.
+*  3. **Le nom du binaire appartient au framework**, pas à ses utilisateurs.
+*     Écrit en dur chez chacun, il ne peut plus jamais changer.
+*
+* La résolution passe donc par le MANIFESTE : Node localise `nodefony` comme il
+* localiserait n'importe quel import, et le champ `bin` dit où est le lanceur.
+* Aucune extension à deviner, aucun shell à ouvrir, aucun chemin à supposer.
+*
+* ## Usage
+*
+* Le résultat se donne à `node`, jamais au système : c'est un script, pas un
+* exécutable.
+*
+* ```ts
+* import { execFileSync } from "node:child_process";
+* import { nodefonyBin } from "nodefony";
+*
+* execFileSync(process.execPath, [nodefonyBin(), "production", "--detach", "--wait"]);
+* ```
+*
+* @param since - d'où résoudre, si ce n'est pas depuis ce module (rare). Un
+*                 appelant installé À CÔTÉ du framework — un shim `create-*`,
+*                 par exemple — passe son propre `import.meta.url` pour que la
+*                 résolution parte de SON arbre de dépendances.
+* @returns Le chemin ABSOLU du script de lancement.
+* @throws Si le paquet `nodefony` est introuvable depuis `depuis` — le message
+*         dit alors que c'est l'INSTALLATION qui manque, pas le chemin qui est
+*         faux.
+*/
+function nodefonyBin(since = import.meta.url) {
+	const require = createRequire(since);
+	let manifeste;
+	try {
+		manifeste = require.resolve("nodefony/package.json");
+	} catch {
+		throw new Error("paquet `nodefony` introuvable depuis " + since + " — l'application est-elle installée (npm install) ?");
+	}
+	const pkg = require("nodefony/package.json");
+	const bin = typeof pkg.bin === "string" ? pkg.bin : pkg.bin?.nodefony ?? "bin/nodefony";
+	return path.join(path.dirname(manifeste), bin);
+}
+//#endregion
+export { nodefonyBin };

package/dist/node/cli/outdated.js

@@ -0,0 +1,144 @@
+import semver from "semver";
+//#region src/cli/outdated.ts
+const SEVERITY_ORDER = {
+	missing: 0,
+	major: 1,
+	minor: 2,
+	patch: 3
+};
+/**
+* Classe le saut qui sépare deux versions.
+*
+* Les variantes de préversion rendues par `semver.diff` (`premajor`, `preminor`…) sont
+* ramenées à leur saut de rang, faute de quoi elles échapperaient à tout regroupement.
+*
+* @param current - version installée, ou `null` si le paquet est absent.
+* @param latest - dernière version publiée.
+* @returns la sévérité du saut ; `"patch"` quand les versions sont illisibles (on ne suppose pas le pire).
+*/
+function classifySeverity(current, latest) {
+	if (!current) return "missing";
+	const from = semver.coerce(current);
+	const to = semver.coerce(latest);
+	if (!from || !to) return "patch";
+	if (to.major > from.major) return "major";
+	if (to.minor > from.minor) return "minor";
+	return "patch";
+}
+/**
+* Agrège le document de `npm outdated --json` en une ligne par paquet.
+*
+* Deux corrections que le brut n'apporte pas : les dépendants sont regroupés au lieu
+* d'être répétés, et un paquet dont la version installée DÉPASSE celle du registre est
+* mis à part — c'est le cas d'un espace de travail local non publié, que `npm` présente
+* comme un retard alors que c'est une avance.
+*
+* @param report - le document rendu par `npm outdated --json` (objet vide si rien).
+* @returns le résumé trié, avec les comptes par catégorie.
+*/
+function aggregateOutdated(report) {
+	const packages = [];
+	const ahead = [];
+	let rawEntries = 0;
+	for (const name of Object.keys(report)) {
+		const raw = report[name];
+		const entries = Array.isArray(raw) ? raw : [raw];
+		if (!entries.length) continue;
+		rawEntries += entries.length;
+		const head = entries[0];
+		const current = head.current ?? null;
+		const dependents = [...new Set(entries.map((e) => e.dependent).filter((d) => typeof d === "string" && d.length > 0))].sort();
+		const pkg = {
+			name,
+			current,
+			wanted: head.wanted,
+			latest: head.latest,
+			severity: classifySeverity(current, head.latest),
+			pinned: current !== null && head.wanted === current,
+			dependents,
+			...head.type ? { type: head.type } : {}
+		};
+		const from = current ? semver.coerce(current) : null;
+		const to = semver.coerce(head.latest);
+		if (from && to && semver.gt(from, to)) ahead.push(pkg);
+		else packages.push(pkg);
+	}
+	packages.sort((a, b) => {
+		const bySeverity = SEVERITY_ORDER[a.severity] - SEVERITY_ORDER[b.severity];
+		return bySeverity !== 0 ? bySeverity : a.name.localeCompare(b.name);
+	});
+	ahead.sort((a, b) => a.name.localeCompare(b.name));
+	return {
+		packages,
+		ahead,
+		counts: {
+			major: packages.filter((p) => p.severity === "major").length,
+			minor: packages.filter((p) => p.severity === "minor").length,
+			patch: packages.filter((p) => p.severity === "patch").length,
+			missing: packages.filter((p) => p.severity === "missing").length,
+			ahead: ahead.length,
+			rawEntries
+		}
+	};
+}
+const SEVERITY_LABEL = {
+	missing: "absent",
+	major: "MAJEUR",
+	minor: "mineur",
+	patch: "correctif"
+};
+/**
+* Résume la liste des dépendants pour l'affichage.
+*
+* @param dependents - noms des espaces de travail qui réclament le paquet.
+* @param all - `true` pour tous les nommer, `false` pour n'en garder que le compte au-delà de trois.
+* @returns une chaîne courte, jamais une énumération de vingt lignes.
+*/
+function formatDependents(dependents, all) {
+	if (!dependents.length) return "—";
+	if (all || dependents.length <= 3) return dependents.join(", ");
+	return `${dependents.length} paquets`;
+}
+/**
+* Compose les lignes du tableau des paquets en retard.
+*
+* Rendu PUR : aucune écriture, aucune couleur — l'appelant décide de la sortie.
+*
+* @param summary - le résumé produit par {@link aggregateOutdated}.
+* @param all - `true` pour nommer tous les dépendants.
+* @returns une ligne par paquet : nom, saut, actuel, souhaité, dernier, dépendants.
+*/
+function toTableRows(summary, all = false) {
+	return summary.packages.map((p) => [
+		p.name,
+		SEVERITY_LABEL[p.severity],
+		p.current ?? "—",
+		p.pinned ? `${p.wanted} (épinglé)` : p.wanted,
+		p.latest,
+		formatDependents(p.dependents, all)
+	]);
+}
+/**
+* Compose la phrase d'en-tête qui dit ce qui a été trouvé — et ce qui a été agrégé.
+*
+* Nommer le nombre d'entrées brutes n'est pas décoratif : c'est ce qui explique
+* pourquoi la sortie tient en quelques lignes là où `npm` en rend des dizaines.
+*
+* @param summary - le résumé produit par {@link aggregateOutdated}.
+* @returns la phrase à afficher au-dessus du tableau.
+*/
+function formatHeadline(summary) {
+	const { counts, packages } = summary;
+	if (!packages.length && !counts.ahead) return "Toutes les dépendances sont à jour.";
+	const parts = [];
+	if (counts.major) parts.push(`${counts.major} majeur${counts.major > 1 ? "s" : ""}`);
+	if (counts.minor) parts.push(`${counts.minor} mineur${counts.minor > 1 ? "s" : ""}`);
+	if (counts.patch) parts.push(`${counts.patch} correctif${counts.patch > 1 ? "s" : ""}`);
+	if (counts.missing) parts.push(`${counts.missing} absent${counts.missing > 1 ? "s" : ""}`);
+	const detail = parts.length ? ` — ${parts.join(", ")}` : "";
+	const shown = packages.length + counts.ahead;
+	const raw = counts.rawEntries > shown ? ` npm en affiche ${counts.rawEntries} lignes : il répète un paquet pour CHAQUE dépendant.` : "";
+	return `${packages.length} paquet${packages.length > 1 ? "s" : ""} en retard${detail}.${raw}`;
+}
+//#endregion
+export { aggregateOutdated, classifySeverity, formatDependents, formatHeadline, toTableRows };