nodefony 7.0.2 → 10.0.0-alpha.2

package/dist/node/service/dev/bootVerdict.js

@@ -0,0 +1,158 @@
+import http from "node:http";
+//#region src/service/dev/bootVerdict.ts
+/**
+* Le verdict de boot d'un runtime, OBSERVÉ DE L'EXTÉRIEUR — une seule implémentation.
+*
+* POURQUOI ce fichier existe : deux appelants ont besoin de la même réponse à la même
+* question, « cette application est-elle AMPUTÉE ? », et ils y répondaient séparément —
+* le superviseur de développement en la journalisant, le lancement détaché pas du tout.
+* Or c'est le second qui sert la production et la suite e2e de toute application
+* générée : la question y était posée par personne, et un module déclaré au manifeste
+* qui ne charge pas rendait 404 sur toutes ses routes, sans un mot.
+*
+* Le canal est HTTP en boucle locale (`/nodefony/kernel/api/livez`), jamais une IPC :
+* c'est une OBSERVATION du process réellement en train de servir, pas une confidence
+* qu'il se fait à lui-même. La route est publique par dessein (sonde k8s) et son champ
+* `degraded` ne nomme personne — les noms restent réservés à l'appelant authentifié.
+* Ici on ne lit qu'un booléen ; les noms, on va les chercher dans le JOURNAL.
+*/
+/** Intervalle de re-sonde tant que le verdict reste inconclusif. */
+const POLL_MS = 250;
+/**
+* Interroge `livez` et rend le verdict de boot, ou pourquoi il n'y en a pas.
+*
+* Aucune de ces situations ne se confond avec « sain » : une sonde muette ne doit ni
+* bloquer un démarrage, ni le certifier.
+*
+* @param port - port en clair du runtime (boucle locale).
+* @param deps - injection du client HTTP, pour éprouver sans réseau.
+* @returns `true` (dégradé), `false` (sain), `"booting"` (verdict pas encore stable),
+*   `"unreachable"` (aucune réponse exploitable).
+*/
+function probeBootDegraded(port, deps = {}) {
+	if (!port || !Number.isInteger(port) || port < 1 || port > 65535) return Promise.resolve("unreachable");
+	return (deps.fetchLivez ?? httpGetLivez)(port).then((body) => {
+		if (body === null) return "unreachable";
+		try {
+			const j = JSON.parse(body);
+			return j.booted ? Boolean(j.degraded) : "booting";
+		} catch {
+			return "unreachable";
+		}
+	});
+}
+/**
+* Re-sonde jusqu'à obtenir un verdict STABLE, ou jusqu'à l'échéance.
+*
+* Sans cette attente, la sonde tomberait dans la course entre l'ouverture des ports et
+* la fin du boot, et crierait « dégradé » sur une application parfaitement saine —
+* c'est-à-dire qu'elle deviendrait une alarme qu'on apprend à ignorer.
+*
+* @param port - port en clair du runtime.
+* @param settleMs - durée maximale d'attente d'un verdict.
+* @param deps - injection du client HTTP et de l'attente, pour éprouver sans réseau.
+* @returns le verdict, ou `null` s'il ne s'est pas stabilisé à temps.
+*/
+async function waitBootVerdict(port, settleMs, deps = {}) {
+	const now = deps.now ?? (() => Date.now());
+	const wait = deps.delay ?? ((ms) => new Promise((r) => {
+		setTimeout(r, ms);
+	}));
+	const deadline = now() + settleMs;
+	for (;;) {
+		if (deps.aborted?.()) return null;
+		const probe = await probeBootDegraded(port, deps);
+		if (probe === "unreachable") return null;
+		if (probe !== "booting") return probe;
+		if (now() >= deadline) return null;
+		await wait(POLL_MS);
+	}
+}
+/**
+* Extrait du journal d'un runtime les modules que le boot a IGNORÉS, avec leur motif.
+*
+* POURQUOI lire le journal plutôt que la route : `livez` ne nomme les modules qu'à un
+* appelant authentifié, et une sonde de démarrage n'a pas d'identité à présenter. Le
+* journal, lui, est le fichier qu'on vient d'écrire — il porte le message que le Kernel
+* a émis en écartant le module, motif compris. Le format lu est celui de
+* `Kernel.loadModulesFromManifest` ; le motif est ce qui suit le tiret cadratin.
+*
+* Fonction PURE : c'est ce qui la rend éprouvable sans démarrer quoi que ce soit.
+*
+* @param journal - contenu brut du journal (les couleurs sont tolérées).
+* @returns une ligne par module ignoré, `nom — motif`, sans doublon et dans l'ordre.
+*/
+function extractSkippedModules(journal) {
+	const withoutColors = journal.replace(/\x1b\[[0-9;]*m/gu, "");
+	const pattern = /MODULE LOAD: échec non bloquant \(fail-soft\) de "([^"]+)" — (.*)$/gmu;
+	const vus = /* @__PURE__ */ new Set();
+	for (const m of withoutColors.matchAll(pattern)) vus.add(`${m[1]} — ${m[2].trim()}`);
+	return [...vus];
+}
+/**
+* Demande au runtime s'il peut SERVIR — question distincte de « ses ports
+* répondent-ils ». Un pod dont le schéma de base est en retard écoute
+* parfaitement et ne sert rien : l'orchestrateur le tient hors du répartiteur de
+* charge, et un rapport qui n'annoncerait que « 2/2 ports UP » serait faux et
+* rassurant à tort — exactement le défaut que ce fichier existe pour éviter.
+*
+* Même canal que {@link probeBootDegraded} (le `livez` du plan d'administration,
+* en boucle locale) : une seule sonde, un seul endroit à corriger.
+*
+* @param port - port en clair du runtime (boucle locale).
+* @param deps - injection du client HTTP, pour éprouver sans réseau.
+* @returns le verdict, ou `null` si rien d'exploitable n'a été obtenu — une
+*   sonde muette ne certifie RIEN, elle se dit muette.
+*/
+function probeReadiness(port, deps = {}) {
+	if (!port || !Number.isInteger(port) || port < 1 || port > 65535) return Promise.resolve(null);
+	return (deps.fetchLivez ?? httpGetLivez)(port).then((body) => {
+		if (body === null) return null;
+		try {
+			const j = JSON.parse(body);
+			if (typeof j.ready !== "boolean") return null;
+			return {
+				ready: j.ready,
+				blocked: j.readinessBlocked ?? 0
+			};
+		} catch {
+			return null;
+		}
+	});
+}
+/**
+* GET `livez` en boucle locale, en clair. Rend `null` sur tout échec — c'est une
+* observation best-effort, jamais un point de rupture du démarrage.
+*
+* @param port - port en clair du runtime.
+* @returns le corps de la réponse, ou `null`.
+*/
+function httpGetLivez(port) {
+	return new Promise((resolve) => {
+		let repondu = false;
+		const conclure = (v) => {
+			if (!repondu) {
+				repondu = true;
+				resolve(v);
+			}
+		};
+		const req = http.get({
+			host: "127.0.0.1",
+			port,
+			path: "/nodefony/kernel/api/livez",
+			timeout: 1500
+		}, (res) => {
+			let data = "";
+			res.setEncoding("utf8");
+			res.on("data", (c) => data += c);
+			res.on("end", () => conclure(data));
+		});
+		req.once("error", () => conclure(null));
+		req.once("timeout", () => {
+			req.destroy();
+			conclure(null);
+		});
+	});
+}
+//#endregion
+export { extractSkippedModules, probeBootDegraded, probeReadiness, waitBootVerdict };

package/dist/node/service/dev/detachedStart.js

@@ -0,0 +1,372 @@
+import "../../cli/sysexits.js";
+import { clearRuntimeState, defaultDevPorts, discoverDevProcesses, formatForeignRuntimes, probePorts, readRuntimeState, signalProcessGroup, splitByProject } from "./devProcess.js";
+import { extractSkippedModules, waitBootVerdict } from "./bootVerdict.js";
+import { DELEGATED_ENV } from "../../bin/resolveLocalCli.js";
+import { closeSync, mkdirSync, openSync, readFileSync, writeSync } from "node:fs";
+import path from "node:path";
+import { spawn } from "node:child_process";
+import http from "node:http";
+import https from "node:https";
+//#region src/service/dev/detachedStart.ts
+/** Marqueur env anti-récursion : posé sur le child pour couper tout re-détachement. */
+const DETACH_CHILD_ENV = "NF_DETACH_CHILD";
+/**
+* Environnement du child détaché — hérité du parent, MOINS ce qui ne se
+* transmet pas.
+*
+* `DELEGATED_ENV` est une garde **anti-boucle de process** : le CLI global la
+* pose sur lui-même juste avant de charger le CLI de l'application, pour que
+* celui-ci exécute au lieu de redéléguer à l'infini. Elle décrit donc un état
+* du process COURANT, pas une intention à propager.
+*
+* La transmettre au child était une panne silencieuse, et coûteuse à lire : le
+* child est relancé sur le binaire d'ENTRÉE (`argv[1]`, le CLI global), et la
+* garde héritée lui interdit précisément la délégation qui l'aurait renvoyé
+* vers le CLI de l'application. Le framework du CLI global bootait alors
+* l'application locale. Mesuré sur une application installée depuis les
+* tarballs : **un seul module chargé sur huit**, puis « profil serveur mais
+* aucun serveur en écoute » — un diagnostic qui ne parle jamais de délégation.
+* Invisible en monorepo lié, où les deux CLI sont le même code.
+*
+* Le child repart donc du binaire d'entrée SANS la garde : il refait le chemin
+* complet du parent, redélègue de lui-même, et exécute le CLI de l'application.
+*
+* @param parent - environnement du process appelant (`process.env`).
+* @param extra - variables propres au lancement (cf `DetachedStartOptions.env`).
+* @returns l'environnement à passer au child.
+*/
+function childEnv(parent, extra) {
+	const env = {
+		...parent,
+		...extra,
+		[DETACH_CHILD_ENV]: "1"
+	};
+	delete env[DELEGATED_ENV];
+	return env;
+}
+/**
+* Drapeaux `node` qui TIENNENT un port — les seuls à ne pas suivre le child.
+*
+* Tout le reste de `process.execArgv` doit le suivre : `--expose-gc`,
+* `--max-old-space-size`, `--import`, `--loader`… Un runtime lancé
+* `node --expose-gc bin/nodefony production --detach` obtenait sinon un serveur SANS
+* ce drapeau, et toute sonde mémoire y devenait un no-op parfaitement muet — le
+* banc mesurait alors le déchet en attente de collecte au lieu du heap retenu.
+*
+* L'inspection fait exception parce que le parent est encore VIVANT pendant que
+* l'enfant démarre (il attend sa readiness) : hériter le même port d'inspection tue
+* l'enfant sur une adresse déjà prise, et le diagnostic ne parle jamais de débogueur.
+*/
+const PORT_HOLDING_FLAGS = /^--(inspect|debug)(-brk|-port|-publish-uid)?(=|$)/u;
+/**
+* Drapeaux `node` à transmettre au runtime détaché.
+*
+* Fonction PURE — c'est ce qui permet de l'éprouver sans lancer de process.
+*
+* @param parentExecArgv - `process.execArgv` du lanceur.
+* @returns les drapeaux à replacer devant le binaire du child.
+*/
+function childExecArgv(parentExecArgv) {
+	return parentExecArgv.filter((a) => !PORT_HOLDING_FLAGS.test(a));
+}
+/** Fenêtre de tick de la boucle d'attente (ms). */
+const TICK_MS = 500;
+/** Nombre de lignes de log remontées au diagnostic d'échec. */
+const TAIL_LINES = 10;
+/**
+* Fenêtre laissée au verdict de boot pour se STABILISER (ms).
+*
+* Les ports TCP acceptent avant que les modules soient debout : sonder trop tôt
+* rendrait « dégradé » sur une application saine, c'est-à-dire une alarme qu'on
+* apprend à ignorer.
+*/
+const DEGRADED_SETTLE_MS = 3e3;
+/**
+* Parse les flags du détacheur depuis argv (après node + bin) et STRIP ces flags
+* des args relayés au child — un `--detach` relayé re-détacherait à l'infini.
+* Fonction PURE (testable sans process).
+*
+* @param args - `process.argv.slice(2)`.
+*/
+function parseDetachArgs(args) {
+	const relayArgs = [];
+	let detach = false;
+	let waitSec = 120;
+	let healthPath;
+	let logFile;
+	let allowDegraded = false;
+	for (let i = 0; i < args.length; i++) {
+		const a = args[i];
+		if (a === "--detach") detach = true;
+		else if (a === "--allow-degraded") allowDegraded = true;
+		else if (a === "--wait" || a.startsWith("--wait=")) {
+			const v = a.includes("=") ? a.split("=")[1] : args[++i];
+			const n = Number.parseInt(v ?? "", 10);
+			if (Number.isInteger(n) && n > 0) waitSec = n;
+		} else if (a === "--health" || a.startsWith("--health=")) healthPath = a.includes("=") ? a.split("=")[1] : args[++i];
+		else if (a === "--log" || a.startsWith("--log=")) logFile = a.includes("=") ? a.split("=")[1] : args[++i];
+		else relayArgs.push(a);
+	}
+	return {
+		detach,
+		waitSec,
+		healthPath,
+		logFile,
+		allowDegraded,
+		relayArgs
+	};
+}
+/** `true` si l'invocation demande un lancement détaché (et n'est PAS déjà le child). */
+function isDetachRequested(args) {
+	return args.includes("--detach") && process.env["NF_DETACH_CHILD"] !== "1";
+}
+/** Contenu brut du journal, ou chaîne vide s'il est illisible. */
+function readLog(logFile) {
+	try {
+		return readFileSync(logFile, "utf8");
+	} catch {
+		return "";
+	}
+}
+/** Dernières lignes non vides d'un fichier de log, ANSI strippé (diagnostic). */
+function tailLog(logFile, n = TAIL_LINES) {
+	try {
+		return readFileSync(logFile, "utf8").replace(/\x1b\[[0-9;]*m/g, "").split("\n").filter((l) => l.trim().length > 0).slice(-n);
+	} catch {
+		return [];
+	}
+}
+/** Dernière ligne de phase du DevSupervisor (`[dev] …`) pour la progression. */
+function lastPhaseLine(logFile) {
+	const lines = tailLog(logFile, 40).filter((l) => l.startsWith("[dev]"));
+	return lines.length > 0 ? lines[lines.length - 1].slice(0, 70) : "";
+}
+/**
+* GET de santé best-effort après readiness des ports : https insecure sur le DERNIER
+* port (convention dev : TLS), fallback http sur le premier. 2 tentatives (le watch
+* peut occuper l'event loop juste après le boot) — n'échoue JAMAIS le lancement :
+* les ports écoutent déjà, un health raté = information, pas un verdict.
+*/
+function probeHealth(ports, healthPath) {
+	const tlsPort = ports[ports.length - 1];
+	const plainPort = ports[0];
+	const attempt = (useTls, tries, resolve) => {
+		const req = (useTls ? https : http).request({
+			hostname: "127.0.0.1",
+			port: useTls ? tlsPort : plainPort,
+			path: healthPath,
+			rejectUnauthorized: false,
+			timeout: 4e3
+		}, (res) => {
+			res.resume();
+			resolve(String(res.statusCode));
+			req.destroy();
+		});
+		const retry = (why) => {
+			if (useTls) attempt(false, tries, resolve);
+			else if (tries > 1) setTimeout(() => attempt(true, tries - 1, resolve), 1500);
+			else resolve(`skipped (${why}) — servers listen OK`);
+		};
+		req.on("error", (e) => {
+			if (e.code !== "ECONNRESET") retry(`ERR ${e.code}`);
+		});
+		req.on("timeout", () => {
+			req.destroy();
+			retry("TIMEOUT");
+		});
+		req.end();
+	};
+	return new Promise((resolve) => attempt(true, 2, resolve));
+}
+/**
+* Spawn le runtime détaché puis attend sa readiness (AU MOINS UN port en écoute).
+*
+* « Au moins un » et pas « tous » : la liste de ports est une CONVENTION du parent
+* (défaut `[5151, 5152]`), pas la topologie réelle de l'app — une app `https: false`
+* n'ouvrira JAMAIS 5152 et un « tous » l'attendrait à vie (faux négatif, vécu).
+* L'état COMPLET port par port reste dans `ports` du résultat (fail-loud : un port
+* attendu fermé est VISIBLE dans le récap, il ne bloque juste pas la readiness).
+*
+* Signaux d'échec (fail-fast, cf en-tête du module) :
+* - le child MEURT avant la readiness → `EX_UNAVAILABLE` + exit code du child + tail log ;
+* - plafond `waitSec` dépassé → group-kill du child (pas de runtime zombie à moitié
+*   booté) + `EX_UNAVAILABLE` + tail log.
+*
+* @returns résultat structuré — l'appelant décide du rendu et du `process.exit`.
+*/
+async function launchDetached(opts) {
+	const ports = opts.ports ?? defaultDevPorts();
+	const waitSec = opts.waitSec ?? 120;
+	const logFile = path.resolve(opts.cwd ?? process.cwd(), opts.logFile);
+	const progress = opts.onProgress ?? (() => {});
+	const cwd = opts.cwd ?? process.cwd();
+	const preflight = await probePorts(ports);
+	const busy = preflight.filter((p) => p.listening);
+	let foreignBusy = false;
+	if (busy.length > 0) {
+		let mineRunning = false;
+		let who = "";
+		try {
+			const { mine, foreign } = splitByProject(discoverDevProcesses(), cwd);
+			mineRunning = mine.length > 0;
+			if (foreign.length > 0) who = " — occupés par un AUTRE projet Nodefony :\n" + formatForeignRuntimes(foreign).join("\n");
+		} catch {}
+		if (mineRunning) return {
+			ok: false,
+			pid: null,
+			exitCode: 69,
+			ports: preflight,
+			logFile,
+			reason: `port(s) déjà en écoute : ${busy.map((p) => p.port).join(", ")} — un runtime de CE projet tourne déjà (nodefony status · nodefony stop)`
+		};
+		foreignBusy = true;
+		progress(`ports ${busy.map((p) => p.port).join(", ")} déjà pris${who}\n   → cette app prendra les premiers ports libres (servers.portPolicy: "auto")`);
+	}
+	clearRuntimeState(cwd);
+	mkdirSync(path.dirname(logFile), { recursive: true });
+	const out = openSync(logFile, "w");
+	const child = spawn(opts.spawnCmd, opts.spawnArgs, {
+		cwd: opts.cwd ?? process.cwd(),
+		stdio: [
+			"ignore",
+			out,
+			out
+		],
+		detached: true,
+		env: childEnv(process.env, opts.env)
+	});
+	let fdClosed = false;
+	const closeFd = () => {
+		if (!fdClosed) {
+			fdClosed = true;
+			closeSync(out);
+		}
+	};
+	child.once("spawn", closeFd);
+	child.once("error", closeFd);
+	child.unref();
+	let exited = false;
+	let exitCode = null;
+	child.once("exit", (code) => {
+		exited = true;
+		exitCode = code;
+	});
+	child.once("error", () => {
+		exited = true;
+	});
+	const ticks = Math.ceil(waitSec * 1e3 / TICK_MS);
+	let watched = ports;
+	for (let i = 1; i <= ticks; i++) {
+		if (exited) return {
+			ok: false,
+			pid: child.pid ?? null,
+			exitCode: 69,
+			ports: await probePorts(watched),
+			logFile,
+			reason: `process mort avant la readiness (exit ${exitCode ?? "?"})`,
+			logTail: tailLog(logFile)
+		};
+		const state = readRuntimeState(cwd);
+		const published = state !== null && state.ports.length > 0;
+		if (published) watched = state.ports;
+		const states = await probePorts(watched);
+		const up = states.filter((p) => p.listening).length;
+		if (up > 0 && (published || !foreignBusy) && !exited) {
+			const health = opts.healthPath ? await probeHealth(watched, opts.healthPath) : void 0;
+			if ((opts.allowDegraded ? null : await waitBootVerdict(watched[0], DEGRADED_SETTLE_MS)) === true) {
+				const skipped = extractSkippedModules(readLog(logFile));
+				if (child.pid) try {
+					signalProcessGroup(child.pid, "SIGKILL");
+				} catch {}
+				return {
+					ok: false,
+					pid: child.pid ?? null,
+					exitCode: 69,
+					ports: states,
+					logFile,
+					modulesSkipped: skipped,
+					reason: "boot DÉGRADÉ — l'application a démarré SANS " + (skipped.length > 0 ? `${skipped.length} module(s) de son manifeste : ${skipped.join(" · ")}` : "au moins un module de son manifeste") + ". Leurs routes répondront 404. Corrige, ou assume avec --allow-degraded.",
+					logTail: tailLog(logFile)
+				};
+			}
+			const desired = state?.desiredPorts;
+			const shifted = desired !== void 0 && (desired.length !== watched.length || desired.some((p, k) => p !== watched[k]));
+			return {
+				ok: true,
+				pid: child.pid ?? null,
+				exitCode: 0,
+				ports: states,
+				logFile,
+				health,
+				desiredPorts: shifted ? desired : void 0
+			};
+		}
+		if (i % 10 === 0) {
+			const phase = lastPhaseLine(logFile);
+			const elapsed = Math.round(i * TICK_MS / 1e3);
+			progress(`booting (${up}/${watched.length} ports, ${elapsed}s)${phase ? ` — ${phase}` : ""}`);
+		}
+		await new Promise((r) => setTimeout(r, TICK_MS));
+	}
+	if (child.pid) try {
+		signalProcessGroup(child.pid, "SIGKILL");
+	} catch {}
+	return {
+		ok: false,
+		pid: child.pid ?? null,
+		exitCode: 69,
+		ports: await probePorts(ports),
+		logFile,
+		reason: `readiness non atteinte après ${waitSec}s — runtime tué (group-kill)`,
+		logTail: tailLog(logFile)
+	};
+}
+/**
+* Point d'entrée du fast-path standalone (`CliKernel.start`) : parse argv, lance le
+* runtime détaché, rend le rapport sur stdout et retourne le code de sortie.
+*
+* @param argv - `process.argv` complet (node + bin + args).
+* @returns code de sortie sémantique (`EX_OK` / `EX_UNAVAILABLE` / `EX_USAGE`).
+*/
+async function runDetachedStart(argv) {
+	const parsed = parseDetachArgs(argv.slice(2));
+	if (parsed.relayArgs.length === 0) {
+		writeSync(1, "--detach exige une commande de runtime (ex: development)\n");
+		return 64;
+	}
+	const cwd = process.cwd();
+	const logFile = parsed.logFile ?? path.join(cwd, "tmp", "nodefony-detached.log");
+	const say = (msg) => {
+		writeSync(1, `>>> ${msg}\n`);
+	};
+	say(`SPAWN nodefony ${parsed.relayArgs.join(" ")} (detached)`);
+	const result = await launchDetached({
+		spawnCmd: process.execPath,
+		spawnArgs: [
+			...childExecArgv(process.execArgv),
+			argv[1],
+			...parsed.relayArgs
+		],
+		cwd,
+		logFile,
+		waitSec: parsed.waitSec,
+		healthPath: parsed.healthPath,
+		allowDegraded: parsed.allowDegraded,
+		onProgress: (m) => say(`... ${m}`)
+	});
+	if (!result.ok) {
+		say(`FATAL — ${result.reason}`);
+		for (const line of result.logTail ?? []) writeSync(1, `  ${line}\n`);
+		say(`log complet : ${result.logFile}`);
+		return result.exitCode;
+	}
+	const portsUp = result.ports.filter((p) => p.listening).map((p) => p.port).join(" | ");
+	say(`READY — ports en écoute : ${portsUp}`);
+	if (result.desiredPorts) say(`⚠️  PORTS DÉCALÉS — config ${result.desiredPorts.join(", ")} déjà pris → cette app écoute sur ${portsUp}. Viser CES ports (nodefony status).`);
+	if (result.health !== void 0) say(`HEALTH ${result.health}`);
+	say(`UP — PID=${result.pid} | log : ${result.logFile}`);
+	say(`arrêt : nodefony stop · état : nodefony status`);
+	return result.exitCode;
+}
+//#endregion
+export { DETACH_CHILD_ENV, childEnv, childExecArgv, isDetachRequested, launchDetached, parseDetachArgs, runDetachedStart };