nodefony 7.0.2 → 10.0.0-alpha.2

package/dist/node/kernel/adminPlane/catalog.js

@@ -0,0 +1,158 @@
+import { isAdminGranted, resolveAdminRole } from "./adminRbac.js";
+//#region src/kernel/adminPlane/catalog.ts
+/** Variables d'un chemin de route (`module/{name}/docs/{slug}` → name, slug). */
+const PATH_VARIABLE = /\{([^}]+)\}/gu;
+/**
+* Noms des variables portées par un chemin de route.
+*
+* @param path - chemin déclaré par le producteur.
+* @returns les noms, dans l'ordre d'apparition.
+*/
+function pathParams(path) {
+	const found = [];
+	for (const match of path.matchAll(PATH_VARIABLE)) if (match[1]) found.push(match[1]);
+	return found;
+}
+/**
+* Projette les capacités de page déclarées, en les ÉVALUANT.
+*
+* `sortable` et `search` sont des fonctions parce que la réponse dépend du
+* store effectivement branché — un backend en curseur ne balaie pas, un
+* annuaire en mémoire ne connaît pas `createdAt`. Les appeler ici est donc la
+* seule façon de publier une capacité vraie ; recopier une liste constante
+* annoncerait un tri que le premier appel refuserait.
+*
+* @param page - la déclaration du producteur.
+* @returns la capacité, telle qu'elle vaut maintenant.
+*/
+function readPageCapabilities(page) {
+	try {
+		return {
+			sortable: page.sortable?.() ?? [],
+			filters: Object.keys(page.filters ?? {}),
+			search: page.search?.() ?? false
+		};
+	} catch {
+		return;
+	}
+}
+/**
+* L'entrée répond-elle à tous les termes cherchés ?
+*
+* Cumulatifs, et non alternatifs : chercher « module docs » veut dire « les
+* deux », sinon la restriction rendrait plus de lignes que l'absence de
+* restriction.
+*/
+function matches(entry, terms) {
+	if (terms.length === 0) return true;
+	const haystack = `${entry.path} ${entry.summary}`.toLowerCase();
+	return terms.every((term) => haystack.includes(term));
+}
+/**
+* Les endpoints du plan d'administration qu'une porte **sans session** peut
+* servir à cet appelant — la règle unique dont dépendent `nodefony_admin_list`
+* ET `nodefony_admin_call`.
+*
+* ⭐ **Ce qui est listé est appelable, et rien d'autre ne l'est.** C'est le même
+* patron que le filtrage des outils MCP à la collecte : un seul point de
+* décision sert la liste et l'exécution, donc il ne peut pas exister d'entrée
+* appelable qu'on n'aurait pas annoncée, ni d'entrée annoncée qui refuserait
+* ensuite. Deux points de décision, c'est celui qu'on relit le moins qui
+* devient le plus permissif.
+*
+* Trois exclusions, toutes comptées et donc dicibles :
+*
+* 1. **Les mutations.** L'idempotence des mutations du plan est une porte du
+*    transport HTTP (`AdminApiController.idempotencyGate`, qui a besoin du
+*    conteneur) ; l'exécuter d'ici sans elle ferait de cette porte une
+*    quatrième voie qui perd ce que les autres gardent — précisément ce que
+*    l'unification de l'exécution vient de supprimer. Elles se compteront tant
+*    qu'elles ne s'appelleront pas.
+* 2. **Les endpoints `public: true`.** Ce ne sont pas des endpoints libres :
+*    ce sont des self-service scopés à `request.user` (`me`, `me/password`,
+*    `sessions/mine`) ou des sondes d'infrastructure. Une porte sans session
+*    n'a pas d'utilisateur ; les servir rendrait « les données de personne » au
+*    mieux, celles d'autrui au pire.
+* 3. **Ce que le rôle de l'appelant n'ouvre pas** — la même décision que
+*    l'exécution ({@link isAdminGranted}), prise sur le même rôle résolu
+*    ({@link resolveAdminRole}), pour que la liste ne promette jamais ce que
+*    l'appel refuserait.
+*
+* @param broker - le service `adminBroker` du conteneur, ou `undefined`.
+* @param caller - qui demande, avec ses rôles RÉELS.
+* @param query - restriction de lecture facultative.
+* @returns les entrées appelables, et le compte de ce qui ne l'est pas.
+*/
+function adminReadCatalog(broker, caller, query) {
+	const terms = query?.q?.toLowerCase().split(/\s+/u).filter((term) => term !== "") ?? [];
+	const view = {
+		entries: [],
+		total: 0,
+		mutations: 0,
+		selfService: 0,
+		denied: 0,
+		filtered: 0
+	};
+	for (const api of broker?.list() ?? []) {
+		const namespace = api.adminNamespace;
+		let endpoints;
+		try {
+			endpoints = api.adminEndpoints();
+		} catch {
+			continue;
+		}
+		for (const endpoint of endpoints) {
+			view.total += 1;
+			if ((endpoint.method ?? "GET") !== "GET") {
+				view.mutations += 1;
+				continue;
+			}
+			if (endpoint.public) {
+				view.selfService += 1;
+				continue;
+			}
+			if (!isAdminGranted(caller.roles, resolveAdminRole(endpoint))) {
+				view.denied += 1;
+				continue;
+			}
+			if (query?.namespace && query.namespace !== namespace) {
+				view.filtered += 1;
+				continue;
+			}
+			const entry = {
+				namespace,
+				path: endpoint.path,
+				method: "GET",
+				summary: endpoint.summary ?? "",
+				params: pathParams(endpoint.path),
+				...endpoint.page ? { page: readPageCapabilities(endpoint.page) } : {}
+			};
+			if (!matches(entry, terms)) {
+				view.filtered += 1;
+				continue;
+			}
+			view.entries.push(entry);
+		}
+	}
+	return view;
+}
+/**
+* Retrouve une entrée APPELABLE par son couple producteur/chemin.
+*
+* Passe par {@link adminReadCatalog} plutôt que de reparcourir le registre :
+* c'est ce qui garantit que l'appel et la liste tranchent la même chose. Une
+* seconde traversée « équivalente » serait exactement la divergence que ce
+* module supprime.
+*
+* @param broker - le service `adminBroker` du conteneur, ou `undefined`.
+* @param caller - qui demande, avec ses rôles RÉELS.
+* @param namespace - producteur visé.
+* @param path - chemin visé, tel que le catalogue le nomme (variables comprises).
+* @returns l'entrée, ou `null` si elle n'est pas appelable par cet appelant.
+*/
+function findAdminReadEntry(broker, caller, namespace, path) {
+	const { entries } = adminReadCatalog(broker, caller, { namespace });
+	return entries.find((entry) => entry.path === path) ?? null;
+}
+//#endregion
+export { adminReadCatalog, findAdminReadEntry };

package/dist/node/kernel/adminPlane/executeAdmin.js

@@ -0,0 +1,78 @@
+import { isAdminGranted } from "./adminRbac.js";
+import nodefonyError from "../../Error.js";
+//#region src/kernel/adminPlane/executeAdmin.ts
+/**
+* Normalise ce qu'un handler a rendu : donnée brute, ou enveloppe.
+*
+* Discrimination volontairement étroite — enveloppe **si et seulement si**
+* `body` est présent AVEC `status` ou `headers`. Un objet métier qui posséderait
+* un champ `body` (une réponse de webhook, un message stocké) n'en est pas une.
+*
+* @param result - le retour du handler, tel quel.
+* @returns l'issue normalisée, statut 200 par défaut.
+*/
+function normalizeAdminResult(result) {
+	if (result !== null && typeof result === "object" && "body" in result && ("status" in result || "headers" in result)) {
+		const envelope = result;
+		return {
+			status: envelope.status ?? 200,
+			headers: envelope.headers,
+			body: envelope.body
+		};
+	}
+	return {
+		status: 200,
+		body: result
+	};
+}
+/**
+* Exécute un endpoint du plan d'administration — **la porte unique**, sans HTTP.
+*
+* ⭐ **Une source, plusieurs portes.** Le data plane est un ensemble de
+* fonctions `IAdminRequest → donnée` ; ce qui les entoure (autorisation,
+* idempotence des mutations, normalisation du retour, traduction des erreurs)
+* est une règle unique, et elle vit ici. La route HTTP montée par le broker, le
+* pont WS-RPC, la commande `inspect` et le serveur MCP appellent tous cette
+* fonction : ils ne se distinguent que par la façon de RÉSOUDRE l'endpoint (par
+* nom de route côté framework, par couple namespace/chemin côté cœur) et par
+* l'emballage de l'issue.
+*
+* Ce que la duplication précédente coûtait, concrètement : le producteur de
+* `module/{name}/docs/{slug}` joint au refus d'une section inconnue le plan de
+* la page (les titres réels). La seconde implémentation ne gardait que le
+* statut — un agent lisait « introuvable » et concluait que la PAGE n'existait
+* pas, alors que seul le nom de section était faux.
+*
+* @param input - endpoint, requête, rôle exigé, porte éventuelle.
+* @returns l'issue, succès comme échec, **corps du producteur préservé**.
+*/
+async function executeAdminEndpoint(input) {
+	const { endpoint, request, requiredRole, gate, onServerError } = input;
+	if (!isAdminGranted(request.roles, requiredRole)) return {
+		status: 403,
+		body: {
+			error: "Forbidden",
+			required: requiredRole
+		}
+	};
+	const verdict = gate ? await gate(request) : null;
+	if (verdict?.shortCircuit) return verdict.shortCircuit;
+	try {
+		const execution = normalizeAdminResult(await endpoint.handler(request));
+		await verdict?.onSuccess?.(execution);
+		return execution;
+	} catch (error) {
+		await verdict?.onFailure?.();
+		if (error instanceof nodefonyError && typeof error.code === "number" && error.code >= 400 && error.code < 500) return {
+			status: error.code,
+			body: { error: error.message }
+		};
+		onServerError?.(error);
+		return {
+			status: 500,
+			body: { error: "Internal admin handler error" }
+		};
+	}
+}
+//#endregion
+export { executeAdminEndpoint, normalizeAdminResult };

package/dist/node/kernel/checks/deep.js

@@ -0,0 +1,335 @@
+import { aggregateOutdated } from "../../cli/outdated.js";
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { spawn } from "node:child_process";
+//#region src/kernel/checks/deep.ts
+/**
+* Étage 3 de `doctor` — ce que le projet DÉCLARE, réellement exécuté.
+*
+* Les autres étages lisent : des fichiers, des manifestes, l'application
+* démarrée. Celui-ci LANCE — les scripts que l'application déclare déjà
+* (`typecheck`, `lint`, `test`) et l'interrogation du registre npm.
+*
+* ## Pourquoi ce n'est pas le comportement par défaut
+*
+* `doctor` rend son verdict en moins d'une seconde, et c'est ce qui le rend
+* lançable en boucle courte, avant chaque commit, dans un job de forge. Lancer
+* une suite de tests et une requête réseau le ferait passer à des dizaines de
+* secondes — et un diagnostic qui coûte une minute cesse d'être lancé. Le dépôt
+* en a la preuve : un lot d'auto-contrôles écrit, juste, et resté un mois sans
+* que personne ne l'exécute, parce qu'il fallait taper huit commandes.
+*
+* D'où `--deep` : deux publics, deux régimes. La boucle courte veut un verdict
+* immédiat ; celui qui prépare un déploiement veut tout.
+*
+* ## Ce que cet étage n'invente pas
+*
+* Il n'implémente AUCUN contrôle en propre. Il appelle les scripts du projet et
+* rend leur verdict — une seule implémentation par règle, celle que le projet a
+* déjà écrite. Redéfinir ici « ce que typecheck devrait vérifier » créerait une
+* seconde vérité qui divergerait de la première au premier ajout.
+*
+* @module
+*/
+/**
+* Le temps au-delà duquel on cesse d'attendre un script, en millisecondes.
+*
+* 🔴 Vécu, et cher : `npm audit` ne rendait pas d'erreur — il PENDAIT cinq
+* minutes par essai et tuait le job de forge. Une commande qui n'a pas de borne
+* de temps n'échoue pas, elle immobilise ; et l'opérateur conclut que l'outil
+* est cassé, jamais que le réseau ne répond pas.
+*/
+const DEFAULT_TIMEOUT_MS = 12e4;
+/**
+* Bornes PAR ÉTAPE — une suite de tests n'est pas un `typecheck`.
+*
+* 🔴 Vécu sur ce dépôt même : une borne unique de deux minutes condamnait
+* d'office la suite de tout projet sérieux. Ici 3 699 tests : `--deep` rendait
+* TOUJOURS « ⏱ npm run test — interrompu », c'est-à-dire un rouge qui ne disait
+* rien du projet et tout de l'instrument. Un outil de diagnostic qui accuse le
+* mesuré pour un défaut de sa propre mesure est pire qu'un outil absent : on
+* apprend à ignorer ce qu'il dit.
+*
+* Les valeurs sont des ORDRES DE GRANDEUR, pas des promesses : ce qui compte
+* est qu'elles soient distinctes, et qu'un dépassement ne se lise pas comme un
+* échec du projet (cf `outcome: "timeout"`, classé EMPÊCHÉ).
+*/
+const STEP_TIMEOUTS = {
+	lint: 12e4,
+	format: 12e4,
+	"format:check": 12e4,
+	typecheck: 3e5,
+	build: 6e5,
+	test: 18e5,
+	"test:unit": 18e5,
+	"test:integration": 18e5,
+	verify: 18e5
+};
+/** La borne à appliquer à une étape, à défaut la borne générale. */
+function timeoutForStep(step) {
+	return STEP_TIMEOUTS[step] ?? DEFAULT_TIMEOUT_MS;
+}
+/** Le temps accordé au registre npm — plus court : c'est du réseau, pas du calcul. */
+const NETWORK_TIMEOUT_MS = 3e4;
+/**
+* Les scripts que le manifeste déclare, parmi ceux qu'on sait lancer.
+*
+* On ne lance QUE ce que le projet déclare : inventer une commande qu'il n'a
+* pas (`npx tsc`, par exemple) reviendrait à juger une application sur un
+* outillage qu'elle n'a pas choisi.
+*
+* @param projectRoot - racine de l'application.
+* @param steps - les noms de scripts à chercher, dans l'ordre d'exécution.
+* @returns les noms présents, et ceux qui manquent.
+*/
+function declaredSteps(projectRoot, steps) {
+	const manifeste = path.join(projectRoot, "package.json");
+	if (!existsSync(manifeste)) return {
+		present: [],
+		missing: [...steps]
+	};
+	let scripts = {};
+	try {
+		scripts = JSON.parse(readFileSync(manifeste, "utf8")).scripts ?? {};
+	} catch {
+		return {
+			present: [],
+			missing: [...steps]
+		};
+	}
+	const present = [];
+	const missing = [];
+	for (const s of steps) if (typeof scripts[s] === "string") present.push(s);
+	else missing.push(s);
+	return {
+		present,
+		missing
+	};
+}
+/**
+* La première ligne qui NOMME l'échec, en sautant l'annonce de l'exécuteur.
+*
+* 🔴 Un script lancé par `npm run` reçoit d'abord `npm notice run <app> <nom>`.
+* Retenir cette ligne explique l'échec par le nom du script, jamais par la
+* cause — et le rapport devient inutile sans qu'on s'en aperçoive : il a
+* l'apparence d'une explication. Le bruit est donc sauté sur les DEUX flux
+* avant de se rabattre sur l'un d'eux.
+*
+* @param stderr - canal d'erreur du script.
+* @param stdout - sa sortie standard.
+* @returns la ligne utile, bornée, ou une chaîne vide s'il s'est tu.
+*/
+function firstUsefulLine(stderr, stdout) {
+	const bruit = /^(?:npm (?:notice|warn|WARN|ERR!)\b|>\s|\$\s|yarn run |pnpm )/u;
+	const streams = [stderr, stdout];
+	for (const f of streams) {
+		const useful = f.split("\n").map((l) => l.trim()).filter((l) => l.length > 0 && !bruit.test(l));
+		if (useful.length > 0) return clamp(useful[0]);
+	}
+	for (const f of streams) {
+		const lines = f.split("\n").filter((l) => l.trim().length > 0);
+		if (lines.length > 0) return clamp(lines[0].trim());
+	}
+	return "";
+}
+/** Borne une explication : une trace entière rend le rapport illisible. */
+function clamp(line) {
+	return line.length > 160 ? `${line.slice(0, 157)}…` : line;
+}
+/**
+* Lance les scripts déclarés, dans l'ordre, et rend leur verdict.
+*
+* L'ordre compte : `typecheck` avant `test`, parce qu'un type faux fait échouer
+* la suite pour une raison qui n'a rien à voir avec elle, et qu'on veut lire la
+* cause d'abord.
+*
+* @param projectRoot - racine de l'application.
+* @param steps - les scripts à lancer, dans l'ordre.
+* @param run - l'exécuteur, injecté pour que la logique s'éprouve sans lancer
+*   quoi que ce soit : une fonction qui appelle `spawnSync` en dur ne se teste
+*   que sur la machine qui l'exécute, c'est-à-dire nulle part.
+* @returns un verdict par script demandé.
+*/
+async function runVerifySteps(projectRoot, steps, run = (step) => runNpmScript(projectRoot, step), report) {
+	const { present } = declaredSteps(projectRoot, steps);
+	const results = [];
+	for (const step of steps) {
+		if (!present.includes(step)) {
+			results.push({
+				step,
+				outcome: "absent",
+				ms: 0
+			});
+			continue;
+		}
+		report?.({
+			step,
+			phase: "start"
+		});
+		const r = await run(step);
+		if (r.status === null) {
+			report?.({
+				step,
+				phase: "done",
+				outcome: "timeout",
+				ms: r.ms
+			});
+			results.push({
+				step,
+				outcome: "timeout",
+				ms: r.ms,
+				detail: `interrompu après ${Math.round(r.ms / 1e3)} s — la borne de CE contrôle (${Math.round(timeoutForStep(step) / 1e3)} s) était trop courte, ce qui ne dit rien du projet. Relance l'étape seule : npm run ${step}`
+			});
+			continue;
+		}
+		report?.({
+			step,
+			phase: "done",
+			outcome: r.status === 0 ? "passed" : "failed",
+			ms: r.ms
+		});
+		results.push(r.status === 0 ? {
+			step,
+			outcome: "passed",
+			ms: r.ms
+		} : {
+			step,
+			outcome: "failed",
+			ms: r.ms,
+			detail: firstUsefulLine(r.stderr, r.stdout)
+		});
+	}
+	return results;
+}
+/**
+* Lance un script npm du projet, borné dans le temps — de façon ASYNCHRONE.
+*
+* 🔴 **`spawnSync` est ce qui empêchait toute animation, et rien ne le disait.**
+* Un appel synchrone bloque la boucle d'évènements de Node : aucun `setInterval`
+* ne s'y déclenche. Le tourniquet de `--deep` peignait donc sa PREMIÈRE image
+* puis restait figé pendant les trente-huit secondes du `typecheck` — le point
+* fixe exact qu'il était censé remplacer.
+*
+* Le défaut ne pouvait pas se voir en éprouvant le tourniquet : celui-ci est
+* juste, et ses vingt-sept cas passent. Il ne se voyait qu'en regardant la
+* CHAÎNE tourner dans un vrai terminal. C'est le motif « la brique éprouvée, la
+* chaîne jamais », et il coûte à chaque fois le même prix.
+*
+* @param projectRoot - la racine de l'application.
+* @param step - le script npm à lancer.
+* @returns son code de sortie (`null` = tué par la borne), ses flux et sa durée.
+*/
+function runNpmScript(projectRoot, step) {
+	const timeout = timeoutForStep(step);
+	const startedAt = Date.now();
+	return new Promise((resolve) => {
+		const child = spawn("npm", ["run", step], {
+			cwd: projectRoot,
+			timeout,
+			shell: process.platform === "win32"
+		});
+		let stdout = "";
+		let stderr = "";
+		child.stdout?.setEncoding("utf8");
+		child.stderr?.setEncoding("utf8");
+		child.stdout?.on("data", (c) => stdout += c);
+		child.stderr?.on("data", (c) => stderr += c);
+		const done = (status) => resolve({
+			status,
+			stderr,
+			stdout,
+			ms: Date.now() - startedAt
+		});
+		child.on("error", (e) => {
+			stderr += `${e.message}\n`;
+			done(1);
+		});
+		child.on("close", (code, signal) => {
+			done(signal ? null : code ?? 1);
+		});
+	});
+}
+/**
+* Le résumé des paquets en retard, via la MÊME agrégation que `nodefony outdated`.
+*
+* `aggregateOutdated` est appelée, jamais recopiée : elle porte le classement
+* par sévérité (majeure / mineure / correctif) et le regroupement par paquet.
+* Une seconde implémentation ici divergerait au premier ajustement, et les deux
+* passeraient leurs propres tests.
+*
+* @param projectRoot - racine de l'application.
+* @param run - l'exécuteur, injecté pour l'épreuve.
+* @returns le résumé, ou la raison de son absence.
+*/
+async function readOutdated(projectRoot, run = () => runNpmOutdated(projectRoot), report) {
+	const debut = Date.now();
+	report?.({
+		step: "outdated",
+		phase: "start"
+	});
+	const r = await run();
+	const annoncer = (outcome) => report?.({
+		step: "outdated",
+		phase: "done",
+		outcome,
+		ms: Date.now() - debut
+	});
+	if (r.failed) {
+		annoncer("unavailable");
+		return {
+			summary: null,
+			reason: "le registre npm n'a pas répondu dans le temps imparti — ce n'est pas un défaut de l'application, et rien n'en est déduit"
+		};
+	}
+	if (r.stdout.trim().length === 0) {
+		annoncer("ok");
+		return {
+			summary: aggregateOutdated({}),
+			reason: ""
+		};
+	}
+	try {
+		const summary = aggregateOutdated(JSON.parse(r.stdout));
+		annoncer("ok");
+		return {
+			summary,
+			reason: ""
+		};
+	} catch {
+		annoncer("unavailable");
+		return {
+			summary: null,
+			reason: "la réponse du registre npm n'était pas lisible"
+		};
+	}
+}
+/**
+* Interroge le registre, borné — le réseau ne se laisse pas attendre.
+*
+* Asynchrone pour la MÊME raison que {@link runNpmScript} : un `spawnSync` fige
+* la boucle d'évènements, donc l'animation de l'attente. Corriger un seul des
+* deux appels aurait laissé le tourniquet immobile pendant les trente secondes
+* de cette étape-ci — une moitié de correctif qu'on aurait crue entière.
+*/
+function runNpmOutdated(projectRoot) {
+	return new Promise((resolve) => {
+		const child = spawn("npm", ["outdated", "--json"], {
+			cwd: projectRoot,
+			timeout: NETWORK_TIMEOUT_MS,
+			shell: process.platform === "win32"
+		});
+		let stdout = "";
+		child.stdout?.setEncoding("utf8");
+		child.stdout?.on("data", (c) => stdout += c);
+		child.on("error", () => resolve({
+			stdout: "",
+			failed: true
+		}));
+		child.on("close", (_code, signal) => resolve({
+			stdout,
+			failed: Boolean(signal)
+		}));
+	});
+}
+//#endregion
+export { declaredSteps, firstUsefulLine, readOutdated, runVerifySteps, timeoutForStep };