nodefony 7.0.2 → 10.0.0-alpha.2

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

@@ -0,0 +1,136 @@
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import path from "node:path";
+//#region src/kernel/checks/lastBoot.ts
+/**
+* Le BILAN du dernier démarrage — `var/last-boot.json`.
+*
+* Le problème qu'il résout n'est pas celui qu'on croit d'abord. Un boot qui
+* ÉCHOUE est visible par construction : l'erreur s'affiche dans le terminal de
+* celui qui vient de lancer. Un boot qui **réussit en dégradé** ne l'est pas —
+* les briques ignorées, les replis annoncés et les modules gatés défilent une
+* fois et disparaissent avec le terminal. L'application démarre, tout paraît
+* sain, et le développeur (ou l'agent) code contre une application amputée.
+*
+* Ce fichier fige donc les DEUX issues. Il sert aussi le cas où la sortie est
+* perdue plutôt que lue : démarrage détaché, conteneur qui sort en 78, tâche
+* d'intégration continue, ou quelqu'un qui arrive après coup et n'a que
+* `nodefony doctor` — le contrôle qui, lui, n'exécute rien.
+*
+* Écrivain (le Kernel) et lecteur (`check`) partagent ce module : le nom, le
+* chemin et la forme de l'enregistrement sont définis ICI et nulle part
+* ailleurs. Deux définitions dériveraient en silence — un producteur qui écrit
+* `phase` quand le lecteur attend `step` ne casse aucun build, il rend
+* simplement un diagnostic vide.
+*
+* Coût : une écriture par démarrage applicatif, hors de tout chemin de requête.
+*/
+/** Emplacement du bilan du SERVEUR, relatif à la racine de l'application. */
+const LAST_BOOT_FILE = path.join("var", "last-boot.json");
+/**
+* Emplacement du bilan d'un démarrage CONSOLE.
+*
+* Un fichier séparé, et non une entrée de plus dans le premier : un `nodefony
+* inspect` lancé POUR diagnostiquer une panne de serveur écrasait la preuve
+* qu'il venait chercher. Deux profils, deux fichiers — c'est la seule forme
+* qui rend l'écrasement structurellement impossible.
+*/
+const LAST_BOOT_CONSOLE_FILE = path.join("var", "last-boot-console.json");
+/**
+* Le fichier où un bilan doit s'écrire, d'après son profil.
+*
+* Une seule règle, un seul endroit : l'écrivain et le lecteur en dépendent, et
+* deux copies divergeraient sans que rien ne le signale.
+*
+* @param profile - profil du démarrage (absent = serveur, par compatibilité
+*   avec les bilans écrits avant que le champ existe).
+* @returns le chemin relatif du fichier.
+*/
+function lastBootFileFor(profile) {
+	return profile === "console" ? LAST_BOOT_CONSOLE_FILE : LAST_BOOT_FILE;
+}
+/**
+* Écrit le bilan, SANS JAMAIS pouvoir aggraver la situation.
+*
+* Volontairement SYNCHRONE. Sur le chemin d'échec, elle est appelée juste avant
+* que l'erreur soit relancée et que l'orchestrateur termine le process : une
+* écriture asynchrone n'aurait aucune garantie d'aboutir avant la sortie — on
+* aurait bâti un bilan qui manque précisément quand il sert.
+*
+* Toute défaillance d'écriture est avalée : un disque plein ou un dossier en
+* lecture seule ne doit pas transformer un démarrage diagnosticable en une
+* seconde erreur qui masque la première.
+*
+* @param appPath - racine de l'application (le dossier qui porte `var/`).
+* @param entry - le bilan à figer.
+*/
+function writeLastBoot(appPath, entry) {
+	try {
+		const file = path.join(appPath, lastBootFileFor(entry.profile));
+		mkdirSync(path.dirname(file), { recursive: true });
+		writeFileSync(file, `${JSON.stringify(entry, null, 2)}\n`, "utf8");
+	} catch {}
+}
+/**
+* Lit un bilan précis, en le validant.
+*
+* @param appPath - racine de l'application inspectée.
+* @param file - chemin relatif du bilan.
+* @returns le bilan, ou `null` s'il est absent ou illisible.
+*/
+function readLastBootFile(appPath, file) {
+	try {
+		const raw = readFileSync(path.join(appPath, file), "utf8");
+		const parsed = JSON.parse(raw);
+		if (parsed.status !== "ok" && parsed.status !== "failed") return null;
+		if (typeof parsed.timestamp !== "string") return null;
+		return parsed;
+	} catch {
+		return null;
+	}
+}
+/**
+* Tous les bilans disponibles — serveur d'abord, console ensuite.
+*
+* L'ordre n'est pas neutre : celui qui lance `doctor` sur une application qui
+* ne répond plus cherche le SERVEUR. Le bilan d'une commande console est utile
+* (il explique souvent pourquoi un `orm:migrate` n'a rien fait) mais il ne
+* doit jamais passer devant.
+*
+* @param appPath - racine de l'application inspectée.
+* @returns les bilans présents, dans l'ordre de lecture. Jamais `null`.
+*/
+function readLastBoots(appPath) {
+	const summaries = [];
+	for (const file of [LAST_BOOT_FILE, LAST_BOOT_CONSOLE_FILE]) {
+		const summary = readLastBootFile(appPath, file);
+		if (summary) summaries.push(summary);
+	}
+	return summaries;
+}
+/**
+* Rend l'ancienneté d'un bilan en clair (« il y a 3 jours »).
+*
+* L'âge n'est pas un ornement : il décide de la conduite à tenir. Un bilan de
+* la minute précédente décrit l'état courant ; un bilan de la semaine dernière
+* peut décrire un problème résolu depuis, et croire l'un pour l'autre fait
+* chercher un défaut qui n'existe plus.
+*
+* @param timestamp - horodatage ISO du bilan.
+* @param now - instant de référence (injecté pour rendre la fonction pure et
+*              donc éprouvable sans dépendre de l'horloge).
+* @returns une formule lisible, ou `"date illisible"` si l'horodatage est cassé.
+*/
+function formatAge(timestamp, now) {
+	const then = Date.parse(timestamp);
+	if (Number.isNaN(then)) return "date illisible";
+	const seconds = Math.max(0, Math.round((now - then) / 1e3));
+	if (seconds < 60) return "il y a moins d'une minute";
+	const minutes = Math.round(seconds / 60);
+	if (minutes < 60) return `il y a ${minutes} minute${minutes > 1 ? "s" : ""}`;
+	const hours = Math.round(minutes / 60);
+	if (hours < 24) return `il y a ${hours} heure${hours > 1 ? "s" : ""}`;
+	const days = Math.round(hours / 24);
+	return `il y a ${days} jour${days > 1 ? "s" : ""}`;
+}
+//#endregion
+export { LAST_BOOT_CONSOLE_FILE, LAST_BOOT_FILE, formatAge, lastBootFileFor, readLastBoots, writeLastBoot };

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

@@ -0,0 +1,330 @@
+import { callAdminEndpoint } from "../inspect/adminSubjects.js";
+import { NO_TARGET, checkGating } from "./gating.js";
+//#region src/kernel/checks/live.ts
+/**
+* `doctor --live` — l'étage 2 : ce que seule l'application DÉMARRÉE peut dire.
+*
+* La lecture pure fait la force de `doctor` : elle répond sur une application
+* qui ne démarre plus. Mais elle est **structurellement incapable** de voir
+* trois choses où l'on tombe en panne — l'état de la base et de ses migrations,
+* la validation d'une zone de firewall par son authentificateur, et ce que le
+* gating de production retire. Aucune de ces vérités n'est dans un fichier :
+* elles naissent au boot.
+*
+* 🔴 **RIEN n'est calculé ici.** Ces vérités ont déjà des producteurs — les
+* mêmes que la console d'administration et que `nodefony inspect` — et le dépôt
+* interdit d'en écrire une seconde version (« 1 RÈGLE = 1 implémentation ») : un
+* verdict recalculé en statique divergerait en silence, et c'est la porte
+* secondaire qu'on croirait sur parole. Ce module APPELLE, traduit un refus en
+* état d'exécution, et rend les phrases du producteur telles quelles.
+*
+* ⚠️ Le core ne peut importer ni l'ORM ni la sécurité (le graphe de dépendances
+* va dans l'autre sens). C'est précisément ce que le plan d'administration
+* permet : on désigne un producteur par son nom (`orm`, `security`), et son
+* absence est une RÉPONSE — « ce module n'est pas chargé » — pas une erreur.
+*/
+/**
+* Les familles que seul un boot peut renseigner.
+*
+* UNE liste, dont le type se dérive : quand la troisième est arrivée, le compte
+* « 2 » était écrit en dur dans trois tests et dans `liveNotRun`, qui les
+* énumérait à la main. Une famille de plus, et chacun d'eux mentait à sa façon.
+*/
+const LIVE_FAMILIES = [
+	"migrations",
+	"firewall",
+	"gating"
+];
+/** `true` si la valeur est un objet non nul — la seule garde avant d'indexer. */
+function isBag(value) {
+	return typeof value === "object" && value !== null;
+}
+/** Lit une chaîne à une clé, ou `undefined` — jamais de `as` aveugle. */
+function readString(bag, key) {
+	if (!isBag(bag)) return void 0;
+	const value = bag[key];
+	return typeof value === "string" ? value : void 0;
+}
+/**
+* La première commande proposée par un producteur, telle qu'il l'a écrite.
+*
+* Le contrat est partagé par l'ORM (`IOrmMigrationAction`) et par le pilote SQL
+* (`IMigrationAction`) : `{ command, args }`. On ne lit que `command` — les
+* arguments servent à qui exécute, pas à qui affiche.
+*/
+function firstAction(payload) {
+	if (!isBag(payload)) return void 0;
+	const actions = payload.nextActions;
+	if (!Array.isArray(actions) || actions.length === 0) return void 0;
+	return readString(actions[0], "command");
+}
+/**
+* Le verdict que le migrateur rend quand il n'y a RIEN à faire.
+*
+* 🔴 `"up-to-date"`, et pas `"ok"`. Ce contrôle comparait à `"ok"` — un mot qui
+* n'existe dans aucune énumération du produit : les verdicts sont
+* `up-to-date | pending | drift | failed | adopt | divergent`
+* (`MigrationVerdictName`, dans le module ORM). Il ne pouvait donc JAMAIS être
+* vert : une base parfaitement à
+* jour était rapportée comme un manquement, en portant sa propre phrase — « le
+* connecteur est à jour » — sous un `✗`. Le verdict et son message se
+* contredisaient dans la même ligne.
+*
+* Rien ne l'a vu parce que le DÉCOR du test posait le MÊME mot inventé pour
+* son cas sain : les deux erreurs se validaient l'une l'autre. Un décor qui
+* parle une autre langue que le produit valide n'importe quoi.
+*
+* Le cœur ne peut pas IMPORTER l'énumération : elle vit dans un module que le
+* cœur ne connaît pas (la dépendance va dans l'autre sens). La valeur est donc
+* recopiée ici — et un cas de `doctorLive.test.ts` la confronte au source du
+* module quand celui-ci est présent, pour que la copie ne puisse pas dériver
+* en silence.
+*/
+const HEALTHY_MIGRATION_VERDICT = "up-to-date";
+/**
+* L'état des migrations du connecteur par défaut.
+*
+* Trois issues, et chacune se DIT : le module n'est pas là, la base ne migre
+* pas par fichiers (ce n'est pas une panne — une base NoSQL résorbe l'écart
+* autrement), ou le verdict est rendu tel quel.
+*/
+async function checkMigrations(broker, caller) {
+	const read = await callAdminEndpoint(broker, {
+		namespace: "orm",
+		path: "migrations",
+		label: "état des migrations"
+	}, caller);
+	if (!read.ok) {
+		if (read.reason === "producer-missing") return {
+			findings: [],
+			execution: {
+				ran: false,
+				reason: "aucun ORM chargé dans cette application — il n'y a pas de base dont l'état pourrait être constaté",
+				short: "aucun ORM",
+				notApplicable: true,
+				unlock: "déclare un module ORM (`use(\"@nodefony/drizzle\")`)"
+			}
+		};
+		if (readString(isBag(read.body) ? read.body.error : void 0, "code") === "NF_MIGRATE_NO_MIGRATIONS") return {
+			findings: [],
+			execution: {
+				ran: false,
+				reason: readString(isBag(read.body) ? read.body.error : void 0, "summary") ?? "cette base ne se met pas à jour par des migrations de schéma",
+				short: "sans migrations",
+				notApplicable: true
+			}
+		};
+		return {
+			findings: [],
+			execution: {
+				ran: false,
+				reason: read.message,
+				short: "non lisible",
+				...read.reason === "endpoint-missing" ? { unlock: "vérifie la version du module ORM" } : {}
+			}
+		};
+	}
+	const verdict = readString(read.data, "verdict");
+	if (verdict === void 0) return {
+		findings: [],
+		execution: {
+			ran: false,
+			reason: "le module ORM a répondu sans verdict de migration — format inattendu, rien ne peut en être conclu",
+			short: "format inattendu"
+		}
+	};
+	if (verdict === HEALTHY_MIGRATION_VERDICT) return {
+		findings: [],
+		execution: { ran: true }
+	};
+	return {
+		execution: { ran: true },
+		findings: [{
+			kind: "migrations-not-ok",
+			message: readString(read.data, "summary") ?? `migrations : verdict « ${verdict} »`,
+			...firstAction(read.data) ? { action: firstAction(read.data) } : {},
+			source: "orm/migrations"
+		}]
+	};
+}
+/**
+* La cohérence de la configuration du firewall, telle que LUI la voit.
+*
+* Le firewall pose son erreur de configuration au boot et loggue en CRITIC
+* **pendant que le boot continue** : la contradiction est donc connue de
+* l'application, et personne ne va la lire. C'est exactement le genre de fait
+* qu'un diagnostic doit remonter — il ne se voit dans aucun fichier, puisqu'il
+* naît de la confrontation d'une zone et de son authentificateur.
+*/
+async function checkFirewall(broker, caller) {
+	const read = await callAdminEndpoint(broker, {
+		namespace: "security",
+		path: "firewall",
+		label: "firewall"
+	}, caller);
+	if (!read.ok) {
+		if (read.reason === "producer-missing") return {
+			findings: [],
+			execution: {
+				ran: false,
+				reason: "aucun module de sécurité chargé — il n'y a pas de zone dont la cohérence pourrait être constatée",
+				short: "sans firewall",
+				notApplicable: true,
+				unlock: "déclare `use(\"@nodefony/security\")`"
+			}
+		};
+		return {
+			findings: [],
+			execution: {
+				ran: false,
+				reason: read.message,
+				short: "non lisible"
+			}
+		};
+	}
+	const description = read.data;
+	const valid = isBag(description) ? description.configValid : void 0;
+	if (typeof valid !== "boolean") return {
+		findings: [],
+		execution: {
+			ran: false,
+			reason: "le module de sécurité a répondu sans dire si sa configuration est valide — format inattendu",
+			short: "format inattendu"
+		}
+	};
+	if (valid) return {
+		findings: [],
+		execution: { ran: true }
+	};
+	const cause = readString(description, "configError");
+	return {
+		execution: { ran: true },
+		findings: [{
+			kind: "firewall-config-invalid",
+			message: "la configuration du firewall est INVALIDE — le pare-feu est en repli fermé, toute requête est capturée" + (cause ? ` : ${cause}` : ""),
+			source: "security/firewall"
+		}]
+	};
+}
+/**
+* Interroge l'application démarrée, et rend ce qu'elle SAIT d'elle-même.
+*
+* Les deux familles sont indépendantes : l'absence d'un module en saute une
+* sans rien dire de l'autre. Aucune ne lève — un producteur en panne devient un
+* état d'exécution lisible, jamais une exception qui emporterait le rapport
+* statique, qui est justement celui dont on a besoin quand tout va mal.
+*
+* @param broker - le service `adminBroker` du conteneur, s'il existe
+* @param caller - l'identité annoncée (l'opérateur local possède le processus)
+* @returns les manquements constatés, et l'état d'exécution de chaque famille
+*/
+async function collectLiveReport(broker, caller, target = null) {
+	const [migrations, firewall, gating] = await Promise.all([
+		checkMigrations(broker, caller),
+		checkFirewall(broker, caller),
+		checkTargetEnv(broker, caller, target)
+	]);
+	return {
+		findings: [
+			...migrations.findings,
+			...firewall.findings,
+			...gating.findings
+		],
+		...gating.gated.length > 0 ? { gatedModules: gating.gated } : {},
+		execution: {
+			migrations: migrations.execution,
+			firewall: firewall.execution,
+			gating: gating.execution
+		}
+	};
+}
+/**
+* Ce que l'environnement visé fera disparaître.
+*
+* Le « ici » ne se devine pas non plus : il vient du même producteur que
+* `nodefony inspect services`, appelé sur l'application qui vient de démarrer.
+* Les deux vues sortent donc du MÊME endpoint, ce qui est la seule façon
+* qu'un diff ne mesure que l'environnement.
+*/
+async function checkTargetEnv(broker, caller, target) {
+	if (!target?.targetEnv) return {
+		findings: [],
+		gated: [],
+		execution: NO_TARGET
+	};
+	const read = await callAdminEndpoint(broker, {
+		namespace: "kernel",
+		path: "services",
+		label: "services enregistrés"
+	}, caller);
+	if (!read.ok) return {
+		findings: [],
+		gated: [],
+		execution: {
+			ran: false,
+			reason: read.message,
+			short: "non lisible"
+		}
+	};
+	if (!Array.isArray(read.data)) return {
+		findings: [],
+		gated: [],
+		execution: {
+			ran: false,
+			reason: "le plan d'administration a répondu autre chose qu'une liste de services — format inattendu, rien ne peut en être conclu",
+			short: "format inattendu"
+		}
+	};
+	const here = read.data.map((row) => ({
+		name: readString(row, "name") ?? "",
+		module: readString(row, "module") ?? ""
+	}));
+	const result = await checkGating({
+		targetEnv: target.targetEnv,
+		manifest: target.manifest,
+		config: target.config,
+		here,
+		readTarget: target.readTarget
+	});
+	return {
+		findings: result.findings.map((f) => ({
+			kind: "service-lost",
+			message: f.message,
+			source: "kernel/services"
+		})),
+		gated: result.gated,
+		execution: result.execution
+	};
+}
+/**
+* L'état d'exécution des deux familles quand l'étage 2 n'a PAS eu lieu.
+*
+* Le cas nominal : `doctor` sans `--live` ne boote pas, donc il ne sait rien de
+* la base ni du firewall — et c'est une abstention à ÉNONCER, pas un silence.
+* Sans cela, un rapport « aucun manquement » se lirait comme un quitus sur des
+* domaines que personne n'a ouverts.
+*
+* @param reason - ce qui a empêché le boot, ou l'absence de demande
+* @param unlock - le geste qui rendrait l'étage 2 possible
+* @param onDemand - `true` si l'étage 2 n'a pas été DEMANDÉ (et non empêché) :
+*   il est alors rapporté sans peser sur le code de sortie, même en mode
+*   strict. Un boot demandé qui ÉCHOUE, lui, reste un empêchement.
+* @returns les deux familles marquées non exécutées, pour la même cause
+*/
+function liveNotRun(reason, unlock, onDemand = false) {
+	const execution = {
+		ran: false,
+		reason,
+		short: onDemand ? "non demandé" : "indisponible",
+		...unlock ? { unlock } : {},
+		...onDemand ? { onDemand: true } : {}
+	};
+	const families = {};
+	for (const family of LIVE_FAMILIES) families[family] = execution;
+	return {
+		findings: [],
+		execution: families
+	};
+}
+//#endregion
+export { LIVE_FAMILIES, collectLiveReport, liveNotRun };