@nodefony/frontend 10.0.0-alpha.1

package/dist/nodefony/service/ViteProcessSupervisor.js

@@ -0,0 +1,589 @@
+import { FrontendSupervisorStartError } from "../src/errors/FrontendError.js";
+import { ViteConfigGenerator } from "./ViteConfigGenerator.js";
+import { browserReachableHost, resolveOriginTemplate } from "../src/remoteDev.js";
+import { createRequire } from "node:module";
+import { signalProcessGroup } from "nodefony";
+import path from "node:path";
+import { spawn } from "node:child_process";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import http from "node:http";
+import https from "node:https";
+//#region nodefony/service/ViteProcessSupervisor.ts
+/**
+* Résout le binaire Vite **une seule fois** (mis en cache module-level).
+*
+* Lancer le VRAI `node vite.js` en direct — au lieu du shim `npx vite` — évite le
+* process intermédiaire npm : 1 process au lieu de 2, et surtout `SIGINT`/`SIGKILL`
+* atteignent **directement** Vite (`npx`/`npm exec` relaie mal les signaux → Vite
+* orphelin → `EADDRINUSE` au restart).
+*
+* ⚠️ On passe par `vite/package.json` + son champ `bin` : la map `exports` de Vite
+* **n'expose pas** `./bin/vite.js` → `require.resolve("vite/bin/vite.js")` throw
+* `ERR_PACKAGE_PATH_NOT_EXPORTED`. `package.json`, lui, est exporté → résolvable.
+*
+* `null` = résolution impossible → fallback `npx` (jamais cassé = résilient).
+* `undefined` = pas encore tenté.
+*/
+let _viteBin;
+function resolveViteBin() {
+	if (_viteBin !== void 0) return _viteBin;
+	try {
+		const pkgPath = createRequire(import.meta.url).resolve("vite/package.json");
+		const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+		const rel = typeof pkg.bin === "string" ? pkg.bin : pkg.bin?.vite;
+		const abs = rel ? path.join(path.dirname(pkgPath), rel) : null;
+		_viteBin = abs && existsSync(abs) ? abs : null;
+	} catch {
+		_viteBin = null;
+	}
+	return _viteBin;
+}
+const DEFAULTS = {
+	autoRestart: true,
+	maxRestarts: 5,
+	restartBackoffBaseMs: 500,
+	restartBackoffMaxMs: 8e3,
+	healthCheckIntervalMs: 3e4,
+	healthCheckFailureThreshold: 3,
+	healthCheckTimeoutMs: 5e3,
+	portRetryAttempts: 3
+};
+/**
+* Un texte (message d'erreur OU sortie brute de Vite) dénonce-t-il un port occupé ?
+*
+* **Source UNIQUE** de cette décision. Elle était dupliquée en deux regex qui ont
+* divergé : l'une cherchait `port X is in use`, alors que Vite écrit
+* `Port 5173 is ALREADY in use`. Résultat, le retry de port ne se déclenchait
+* jamais et la seconde app perdait tout son frontend — un conflit de port pourtant
+* parfaitement rattrapable. On tolère donc les deux formulations, et on ne
+* l'écrit qu'ici (deux implémentations d'une même règle = dérive garantie).
+*/
+function isPortInUseMessage(text) {
+	return /EADDRINUSE/i.test(text) || /address already in use/i.test(text) || /port\s+\d+\s+is\s+(?:already\s+)?in use/i.test(text);
+}
+/**
+* Message d'échec d'un boot qui n'a jamais rendu la main dans le temps imparti —
+* en y REPORTANT ce que vite avait déjà dit.
+*
+* Le conflit de port ne se voit que dans la sortie du child. Le rejet par
+* échéance ne portait que la durée : un boot qui annonçait « Port 5173 is
+* already in use » puis restait pendu (vite ne meurt pas toujours, et sur une
+* application réelle le pré-bundling tient l'échéance) sortait sous le libellé
+* `timeout after …`, que le détecteur de port occupé ne reconnaît pas. Le repli
+* sur `port+1` existait et n'était jamais atteint — la sortie d'échec choisie
+* décidait à elle seule si la 2ᵉ application aurait un frontend.
+*
+* Fonction PURE : la règle « ce qu'on a OBSERVÉ prime sur la façon dont on a
+* échoué » se teste sans spawn, donc sans dépendre d'une course entre l'écriture
+* de l'erreur et la mort du process.
+*
+* @param timeoutMs - échéance dépassée.
+* @param observed - sortie brute accumulée du child (stdout + stderr).
+* @returns message d'erreur, préfixé `EADDRINUSE:` si un port occupé est dénoncé.
+*/
+function startupTimeoutMessage(timeoutMs, observed) {
+	const base = `timeout after ${timeoutMs}ms`;
+	return isPortInUseMessage(observed) ? `EADDRINUSE: ${base} — vite a annoncé un port occupé sans rendre la main` : base;
+}
+/**
+* Superviseur Vite résilient — branche POC `poc/frontend-child`.
+*
+* Garanties :
+*  - Idempotent : appels concurrents à `start()` partagent la même promesse.
+*  - Auto-restart : crash inattendu → restart avec backoff exponentiel borné.
+*  - Port conflict : retry sur port+1 jusqu'au plafond `portRetryAttempts`.
+*  - Health check : ping périodique, kill+restart sur N échecs consécutifs.
+*  - Cleanup strict : listeners + timers tracés et libérés au `stop()`.
+*
+* Tous les listeners sur `child` sont supprimés explicitement avant qu'on
+* laisse le child mourir (évite memory leak entre restarts).
+*/
+var ViteProcessSupervisor = class {
+	opts;
+	cfg;
+	generator = new ViteConfigGenerator();
+	child = null;
+	state = "idle";
+	resolvedPort = null;
+	/** Origine publique du spawn courant (source unique des URLs — cf status). */
+	resolvedOrigin = null;
+	lastError = null;
+	entries = [];
+	configFilePath = null;
+	restartCount = 0;
+	healthFailures = 0;
+	healthCheckTimer = null;
+	restartTimer = null;
+	startPromise = null;
+	stopPromise = null;
+	willingShutdown = false;
+	/** Kill VOULU par le health check (recovery) : le prochain exit doit relancer. */
+	expectRestartKill = false;
+	/**
+	* Signal d'arrêt reçu par NOTRE process (Ctrl+C au groupe foreground, SIGTERM
+	* d'un orchestrateur) → tout exit de Vite est un ARRÊT, jamais un crash.
+	* Indispensable : Vite intercepte SIGINT et sort `code=130, signal=null` —
+	* indiscernable d'un crash côté exit event, et `willingShutdown` (posé par le
+	* stop du kernel) arrive APRÈS la mort de Vite (race sans IPC, vécu Ctrl+C :
+	* « vite restart #1 failed » en ERROR sur un arrêt normal).
+	*/
+	markShutdown = () => {
+		this.willingShutdown = true;
+	};
+	/**
+	* Listeners attachés au child courant — drainés à chaque mort du child.
+	* Sans ça, le child gardé en référence (avant GC) accumule des handlers
+	* entre restarts → MaxListenersExceededWarning + leak.
+	*/
+	childListeners = [];
+	constructor(opts) {
+		this.opts = opts;
+		this.cfg = {
+			autoRestart: opts.autoRestart ?? DEFAULTS.autoRestart,
+			maxRestarts: opts.maxRestarts ?? DEFAULTS.maxRestarts,
+			restartBackoffBaseMs: opts.restartBackoffBaseMs ?? DEFAULTS.restartBackoffBaseMs,
+			restartBackoffMaxMs: opts.restartBackoffMaxMs ?? DEFAULTS.restartBackoffMaxMs,
+			healthCheckIntervalMs: opts.healthCheckIntervalMs ?? DEFAULTS.healthCheckIntervalMs,
+			healthCheckFailureThreshold: opts.healthCheckFailureThreshold ?? DEFAULTS.healthCheckFailureThreshold,
+			healthCheckTimeoutMs: opts.healthCheckTimeoutMs ?? DEFAULTS.healthCheckTimeoutMs,
+			portRetryAttempts: opts.portRetryAttempts ?? DEFAULTS.portRetryAttempts
+		};
+	}
+	async start(entries, _viteConfigUnused) {
+		if (this.state === "ready") return;
+		if (this.startPromise) return this.startPromise;
+		if (this.state === "stopping") throw new FrontendSupervisorStartError("cannot start while stopping");
+		if (entries.length === 0) throw new FrontendSupervisorStartError("no entries");
+		this.entries = entries;
+		this.willingShutdown = false;
+		this.restartCount = 0;
+		this.lastError = null;
+		process.once("SIGINT", this.markShutdown);
+		process.once("SIGTERM", this.markShutdown);
+		this.startPromise = this.spawnWithPortRetry();
+		try {
+			await this.startPromise;
+			this.startHealthCheck();
+		} finally {
+			this.startPromise = null;
+		}
+	}
+	async stop() {
+		if (this.state === "idle" || this.state === "stopped") return;
+		if (this.stopPromise) return this.stopPromise;
+		this.stopPromise = this.doStop();
+		try {
+			await this.stopPromise;
+		} finally {
+			this.stopPromise = null;
+		}
+	}
+	status() {
+		return {
+			state: this.state,
+			host: this.opts.devHost,
+			origin: this.resolvedOrigin,
+			port: this.resolvedPort ?? this.opts.devPort,
+			pid: this.child?.pid ?? null,
+			lastError: this.lastError,
+			entries: this.entries,
+			https: !!this.opts.https,
+			restartCount: this.restartCount,
+			healthFailures: this.healthFailures,
+			portRetries: this.portRetries
+		};
+	}
+	/**
+	* Essaie de spawn Vite en variant le port si EADDRINUSE. Le port résolu
+	* est stocké dans `resolvedPort` (utilisé par status() + TemplateHelper).
+	*/
+	async spawnWithPortRetry() {
+		const maxAttempts = this.cfg.portRetryAttempts;
+		let lastErr = null;
+		this.portRetries = 0;
+		for (let i = 0; i <= maxAttempts; i++) {
+			const port = this.opts.devPort + i;
+			try {
+				await this.attemptSpawn(port);
+				return;
+			} catch (e) {
+				lastErr = e instanceof Error ? e : new Error(String(e));
+				if (this.isPortInUseError(lastErr) && i < maxAttempts) {
+					this.opts.logger.info(`port ${port} unavailable — retrying on ${port + 1}`);
+					this.portRetries += 1;
+					continue;
+				}
+				throw lastErr;
+			}
+		}
+		throw lastErr ?? new FrontendSupervisorStartError("port retry exhausted");
+	}
+	/** Replis de port du DERNIER démarrage — cf `IViteSupervisorStatus.portRetries`. */
+	portRetries = 0;
+	isPortInUseError(e) {
+		return isPortInUseMessage(e.message);
+	}
+	/** Spawn Vite sur un port donné et attend le ready. */
+	async attemptSpawn(port) {
+		this.state = "starting";
+		this.cleanupChildListeners();
+		const moduleRoot = this.entries[0].root;
+		this.configFilePath = path.resolve(moduleRoot, "vite.config.generated.mjs");
+		const scheme = this.opts.https ? "https" : "http";
+		const tpl = this.opts.publicOriginTemplate;
+		const resolved = tpl ? resolveOriginTemplate(tpl, port) : null;
+		if (tpl && !resolved) this.opts.logger.error(`publicOrigin invalide (« ${tpl} ») — attendu scheme://host[:port|:{port}] ; origine locale dérivée utilisée à la place`);
+		if (resolved && !tpl.includes("{port}") && port !== this.opts.devPort) this.opts.logger.error(`publicOrigin figée (« ${tpl} ») mais Vite écoute sur ${port} (≠ ${this.opts.devPort}) — ajouter {port} au template ou libérer le port d'origine`);
+		const viteOrigin = resolved?.origin ?? `${scheme}://${browserReachableHost(this.opts.devHost)}:${port}`;
+		this.resolvedOrigin = viteOrigin;
+		const content = this.generator.toMjs(this.entries, "development", {
+			backendOrigin: this.opts.backendOrigin,
+			viteOrigin,
+			https: this.opts.https,
+			allowedHosts: this.opts.allowedHosts,
+			hmr: resolved?.hmr
+		});
+		writeFileSync(this.configFilePath, content, "utf8");
+		this.opts.logger.debug?.(`vite config written: ${this.configFilePath}`);
+		const args = [
+			"vite",
+			"--config",
+			this.configFilePath,
+			"--host",
+			this.opts.devHost,
+			"--port",
+			String(port),
+			...this.opts.nodeEnv ? ["--mode", this.opts.nodeEnv] : []
+		];
+		const viteBin = resolveViteBin();
+		if (!viteBin && process.platform === "win32") {
+			this.state = "errored";
+			this.lastError = "vite binary unresolved (win32)";
+			throw new FrontendSupervisorStartError("binaire vite irrésoluble et fallback npx non portable sous Windows — installer vite en devDependency de l'application");
+		}
+		const spawnCmd = viteBin ? process.execPath : "npx";
+		const spawnArgs = viteBin ? [viteBin, ...args.slice(1)] : args;
+		const psLabel = `nodefony-vite[${this.entries.map((e) => e.entryName).join("+")}]`;
+		this.opts.logger.debug?.(viteBin ? `vite spawn direct (node ${viteBin})` : "vite spawn via npx (fallback — résolution directe indisponible)");
+		try {
+			this.child = spawn(spawnCmd, spawnArgs, {
+				cwd: this.opts.cwd,
+				argv0: psLabel,
+				stdio: [
+					"ignore",
+					"pipe",
+					"pipe"
+				],
+				detached: false,
+				env: {
+					...process.env,
+					...this.opts.nodeEnv ? { NODE_ENV: this.opts.nodeEnv } : {},
+					...this.opts.extraEnv,
+					FORCE_COLOR: "0",
+					NO_COLOR: "1"
+				}
+			});
+		} catch (e) {
+			this.state = "errored";
+			this.lastError = e instanceof Error ? e.message : String(e);
+			throw new FrontendSupervisorStartError("spawn failed", e);
+		}
+		await this.waitReady(port);
+		this.opts.logger.debug?.(`vite ready on port ${port}`);
+	}
+	async waitReady(_expectedPort) {
+		await new Promise((resolve, reject) => {
+			const child = this.child;
+			if (!child) {
+				reject(new FrontendSupervisorStartError("no child"));
+				return;
+			}
+			let resolved = false;
+			const timeout = setTimeout(() => {
+				if (resolved) return;
+				resolved = true;
+				this.state = "errored";
+				if (child.exitCode === null && child.signalCode === null) this.signalTree(child, "SIGKILL");
+				const msg = startupTimeoutMessage(this.opts.startupTimeoutMs, buffer);
+				this.lastError = msg;
+				reject(new FrontendSupervisorStartError(msg));
+			}, this.opts.startupTimeoutMs);
+			const localRe = /Local:\s+https?:\/\/([^:\s]+):(\d+)/;
+			const ansiRe = /\x1b\[[0-9;]*m/g;
+			const viteOwnPrefixRe = /^\d{1,2}:\d{2}:\d{2}\s+\[vite\]\s*|^\[vite\]\s*/;
+			let buffer = "";
+			const pipeClean = (raw, level) => {
+				if (!this.opts.pipeLogs) return;
+				for (const line of raw.split(/\r?\n/)) {
+					const stripped = line.replace(ansiRe, "").replace(viteOwnPrefixRe, "").trim();
+					if (!stripped) continue;
+					if (level === "error") this.opts.logger.error(`[vite] ${stripped}`);
+					else this.opts.logger.info(`[vite] ${stripped}`);
+				}
+			};
+			const onStdout = (chunk) => {
+				const txt = chunk.toString();
+				pipeClean(txt, "info");
+				if (resolved) return;
+				buffer += txt.replace(ansiRe, "");
+				const m = buffer.match(localRe);
+				if (m) {
+					this.resolvedPort = parseInt(m[2], 10);
+					this.state = "ready";
+					this.healthFailures = 0;
+					resolved = true;
+					buffer = "";
+					clearTimeout(timeout);
+					resolve();
+				}
+			};
+			const onStderr = (chunk) => {
+				const txt = chunk.toString();
+				pipeClean(txt, "error");
+				if (resolved) return;
+				buffer += txt.replace(ansiRe, "");
+				const m = buffer.match(localRe);
+				if (m) {
+					this.resolvedPort = parseInt(m[2], 10);
+					this.state = "ready";
+					this.healthFailures = 0;
+					resolved = true;
+					buffer = "";
+					clearTimeout(timeout);
+					resolve();
+				}
+			};
+			const onExit = (code, signal) => {
+				if (!resolved) {
+					resolved = true;
+					clearTimeout(timeout);
+					if (this.willingShutdown) {
+						this.state = "stopped";
+						this.lastError = null;
+						reject(new FrontendSupervisorStartError("arrêt demandé pendant le boot de vite (shutdown, pas une panne)"));
+						return;
+					}
+					const msg = `vite exited (code=${code}, signal=${signal}) before ready`;
+					this.state = "errored";
+					this.lastError = msg;
+					if (isPortInUseMessage(buffer)) reject(new FrontendSupervisorStartError("EADDRINUSE: " + msg));
+					else reject(new FrontendSupervisorStartError(msg));
+				}
+			};
+			const onError = (err) => {
+				if (resolved) return;
+				resolved = true;
+				clearTimeout(timeout);
+				this.state = "errored";
+				this.lastError = err.message;
+				reject(new FrontendSupervisorStartError(err.message, err));
+			};
+			this.trackListener(child.stdout, "data", onStdout);
+			this.trackListener(child.stderr, "data", onStderr);
+			this.trackListener(child, "exit", onExit);
+			this.trackListener(child, "error", onError);
+		});
+		this.attachRuntimeExitHandler();
+	}
+	/**
+	* Après que Vite est ready, on attache un handler qui distingue :
+	*  - shutdown volontaire (willingShutdown=true → state=stopped, no restart)
+	*  - crash inattendu (state=ready au moment du exit → scheduleRestart)
+	*/
+	attachRuntimeExitHandler() {
+		if (!this.child) return;
+		const onRuntimeExit = (code, signal) => {
+			this.cleanupChildListeners();
+			this.opts.logger.info(`[vite] exited (code=${code}, signal=${signal})`);
+			if (this.willingShutdown) {
+				this.state = "stopped";
+				this.child = null;
+				return;
+			}
+			if (this.expectRestartKill) this.expectRestartKill = false;
+			else if (signal === "SIGINT" || signal === "SIGTERM" || signal === "SIGHUP") {
+				this.state = "stopped";
+				this.child = null;
+				this.opts.logger.info(`[vite] arrêté (${signal} — signal d'arrêt) : pas de relance`);
+				return;
+			}
+			this.state = "crashed";
+			this.lastError = `crashed (code=${code}, signal=${signal})`;
+			this.child = null;
+			if (this.cfg.autoRestart) this.scheduleRestart();
+			else this.state = "errored";
+		};
+		this.trackListener(this.child, "exit", onRuntimeExit);
+	}
+	scheduleRestart() {
+		if (this.restartCount >= this.cfg.maxRestarts) {
+			this.state = "errored";
+			this.lastError = `max restarts (${this.cfg.maxRestarts}) reached`;
+			this.opts.logger.error(this.lastError);
+			this.stopHealthCheck();
+			return;
+		}
+		const delay = Math.min(this.cfg.restartBackoffBaseMs * 2 ** this.restartCount, this.cfg.restartBackoffMaxMs);
+		this.restartCount++;
+		this.state = "restarting";
+		this.opts.logger.info(`vite restart #${this.restartCount}/${this.cfg.maxRestarts} in ${delay}ms`);
+		this.stopHealthCheck();
+		this.restartTimer = setTimeout(() => {
+			this.restartTimer = null;
+			if (this.willingShutdown) return;
+			this.spawnWithPortRetry().then(() => {
+				this.opts.logger.info(`vite restart #${this.restartCount} succeeded`);
+				this.startHealthCheck();
+			}).catch((e) => {
+				this.opts.logger.error(`vite restart #${this.restartCount} failed: ${e?.message ?? e}`);
+				this.state = "crashed";
+				this.scheduleRestart();
+			});
+		}, delay);
+	}
+	startHealthCheck() {
+		if (this.cfg.healthCheckIntervalMs <= 0) return;
+		this.stopHealthCheck();
+		this.healthFailures = 0;
+		this.healthCheckTimer = setInterval(() => {
+			this.pingVite().then(() => {
+				if (this.healthFailures > 0) this.opts.logger.info(`vite healthcheck recovered after ${this.healthFailures} failure(s)`);
+				this.healthFailures = 0;
+				if (this.restartCount > 0 && this.state === "ready") {
+					this.opts.logger.info(`vite stable après restart — budget de restarts réarmé (était ${this.restartCount}/${this.cfg.maxRestarts})`);
+					this.restartCount = 0;
+				}
+			}).catch((e) => {
+				this.healthFailures++;
+				this.opts.logger.error(`vite healthcheck failed (${this.healthFailures}/${this.cfg.healthCheckFailureThreshold}): ${e?.message ?? e}`);
+				if (this.healthFailures >= this.cfg.healthCheckFailureThreshold && this.state === "ready") {
+					this.opts.logger.error(`vite unhealthy — killing child to trigger restart`);
+					this.expectRestartKill = true;
+					this.killChild();
+				}
+			});
+		}, this.cfg.healthCheckIntervalMs);
+	}
+	stopHealthCheck() {
+		if (this.healthCheckTimer) {
+			clearInterval(this.healthCheckTimer);
+			this.healthCheckTimer = null;
+		}
+	}
+	/**
+	* Ping HTTP(S) GET sur la racine de Vite. Considère réussi si réception de
+	* headers (même 4xx — Vite ne renvoie pas forcément 200 à `/`).
+	*/
+	pingVite() {
+		return new Promise((resolve, reject) => {
+			const port = this.resolvedPort ?? this.opts.devPort;
+			const req = (this.opts.https ? https : http).request({
+				hostname: browserReachableHost(this.opts.devHost),
+				port,
+				path: "/",
+				method: "GET",
+				rejectUnauthorized: false,
+				timeout: this.cfg.healthCheckTimeoutMs
+			}, (res) => {
+				res.resume();
+				resolve();
+			});
+			req.on("error", (e) => reject(e));
+			req.on("timeout", () => {
+				req.destroy();
+				reject(/* @__PURE__ */ new Error("healthcheck timeout"));
+			});
+			req.end();
+		});
+	}
+	/** Stop volontaire — n'enclenche PAS l'auto-restart. */
+	async doStop() {
+		this.willingShutdown = true;
+		process.removeListener("SIGINT", this.markShutdown);
+		process.removeListener("SIGTERM", this.markShutdown);
+		this.state = "stopping";
+		if (this.restartTimer) {
+			clearTimeout(this.restartTimer);
+			this.restartTimer = null;
+		}
+		this.stopHealthCheck();
+		const child = this.child;
+		if (!child) {
+			this.state = "stopped";
+			return;
+		}
+		return new Promise((resolve) => {
+			let sigKillTimer = null;
+			let settled = false;
+			const done = () => {
+				if (settled) return;
+				settled = true;
+				child.removeListener("exit", done);
+				this.cleanupChildListeners();
+				this.child = null;
+				this.state = "stopped";
+				if (sigKillTimer) clearTimeout(sigKillTimer);
+				resolve();
+			};
+			child.once("exit", done);
+			if (this.signalTree(child, "SIGINT") === "gone") {
+				done();
+				return;
+			}
+			sigKillTimer = setTimeout(() => {
+				const c = this.child;
+				if (c && c.exitCode === null && c.signalCode === null) this.signalTree(c, "SIGKILL");
+			}, 3e3);
+		});
+	}
+	/** Force kill du child (pour les health checks failing). Le exit handler gère le restart. */
+	killChild() {
+		if (!this.child) return;
+		this.signalTree(this.child, "SIGTERM");
+	}
+	/**
+	* Envoie un signal à l'ARBRE de Vite — lui et ses propres enfants, à commencer par
+	* le service esbuild que Vite lance pour la pré-optimisation des dépendances.
+	*
+	* `child.kill()` n'atteint que Vite. Sous POSIX cela suffit en pratique : Vite n'est
+	* pas leader de son groupe (`detached: false`, voulu — un Ctrl+C terminal doit
+	* l'atteindre), donc le comportement ici est inchangé, et l'arbre est de toute façon
+	* emporté par le groupe du superviseur de développement. Sous Windows il n'y a pas de
+	* groupe du tout : les descendants survivaient à chaque arrêt, et `stopDev()` laissait
+	* un service esbuild derrière lui.
+	*
+	* Une seule implémentation dans le dépôt ({@link signalProcessGroup}, cœur) : groupe
+	* POSIX ou `taskkill /T` selon la plateforme. La recopier ici aurait fait réapparaître
+	* l'angle mort qu'on venait de fermer dans le superviseur de développement.
+	*
+	* @returns ce qui a pu être atteint. `gone` = plus rien à tuer, donc plus aucun `exit`
+	*   à attendre : c'est un VERDICT, là où l'arrêt reposait jusqu'ici sur une exception
+	*   remontée par `child.kill()`. Une exception dit qu'un appel a échoué, pas ce qu'il
+	*   est advenu du process — et elle disparaît dès qu'un intermédiaire la rattrape.
+	*/
+	signalTree(child, signal) {
+		if (typeof child.pid !== "number") try {
+			child.kill(signal);
+			return "single";
+		} catch {
+			return "gone";
+		}
+		return signalProcessGroup(child.pid, signal);
+	}
+	trackListener(target, event, fn) {
+		target.on(event, fn);
+		this.childListeners.push({
+			target,
+			event,
+			fn
+		});
+	}
+	cleanupChildListeners() {
+		for (const { target, event, fn } of this.childListeners) try {
+			target.removeListener(event, fn);
+		} catch {}
+		this.childListeners = [];
+	}
+};
+//#endregion
+export { ViteProcessSupervisor, ViteProcessSupervisor as default, isPortInUseMessage, startupTimeoutMessage };

package/dist/nodefony/src/FrontendAdminApi.js

@@ -0,0 +1,113 @@
+import { createRequire } from "node:module";
+import path from "node:path";
+import { existsSync, readFileSync } from "node:fs";
+//#region nodefony/src/FrontendAdminApi.ts
+const requireFrom = createRequire(import.meta.url);
+const versionCache = /* @__PURE__ */ new Map();
+/**
+* Lit la `version` d'un package installé (best-effort, jamais throw). Tente d'abord
+* `<pkg>/package.json` (la plupart l'exportent), sinon remonte depuis le main résolu
+* jusqu'au `package.json` du package. Résultat caché (lu une seule fois).
+*/
+function pkgVersion(pkg) {
+	const cached = versionCache.get(pkg);
+	if (cached !== void 0) return cached ?? void 0;
+	let v = null;
+	try {
+		const p = requireFrom.resolve(`${pkg}/package.json`);
+		v = JSON.parse(readFileSync(p, "utf8")).version ?? null;
+	} catch {
+		try {
+			let dir = path.dirname(requireFrom.resolve(pkg));
+			for (let i = 0; i < 6 && dir; i++) {
+				const cand = path.join(dir, "package.json");
+				if (existsSync(cand)) {
+					const j = JSON.parse(readFileSync(cand, "utf8"));
+					if (j.name === pkg) {
+						v = j.version ?? null;
+						break;
+					}
+				}
+				const parent = path.dirname(dir);
+				if (parent === dir) break;
+				dir = parent;
+			}
+		} catch {
+			v = null;
+		}
+	}
+	versionCache.set(pkg, v);
+	return v ?? void 0;
+}
+/** Package npm du framework UI derrière un type de preset (pour la version). */
+function frameworkPkg(type) {
+	switch (type) {
+		case "react19": return "react";
+		case "vue3": return "vue";
+		case "angular": return "@angular/core";
+		default: return null;
+	}
+}
+/** Mappe un statut superviseur vers la vue sûre (sans paths) + versions framework. */
+function toView(family, status) {
+	return {
+		family,
+		state: status.state,
+		host: status.host,
+		origin: status.origin,
+		port: status.port,
+		pid: status.pid,
+		https: status.https,
+		restartCount: status.restartCount,
+		healthFailures: status.healthFailures,
+		entries: status.entries.map((e) => {
+			const pkg = frameworkPkg(e.type);
+			return {
+				entryName: e.entryName,
+				type: e.type,
+				version: pkg ? pkgVersion(pkg) : void 0
+			};
+		})
+	};
+}
+/**
+* Construit le snapshot frontend (état Vite) — lecture pure, jamais throw.
+*
+* @param service - le {@link FrontendService} (résolu du container).
+* @returns la vue sûre prête à `renderJson` / push realtime.
+*/
+function buildFrontendStatus(service) {
+	const bundles = service.statusAll().map((b) => toView(b.family, b.status));
+	const primary = toView("default", service.status());
+	return {
+		available: bundles.some((b) => b.state === "ready"),
+		vite: pkgVersion("vite"),
+		primary,
+		bundles
+	};
+}
+const descriptor = {
+	label: "Frontend",
+	icon: "bolt",
+	order: 6
+};
+/**
+* Construit le producteur `IAdminApi` du frontend (namespace `"frontend"`).
+*
+* @param service - le {@link FrontendService} à introspecter.
+* @returns le contrat admin, prêt à `broker.register()`.
+*/
+function createFrontendAdminApi(service) {
+	const endpoints = [{
+		path: "vite",
+		summary: "État du superviseur Vite (dev) : process (pid), port réel, état (HMR actif si ready), bundles servis. Vide en prod (Vite ne tourne pas — UI servie par le bundle compilé).",
+		handler: () => buildFrontendStatus(service)
+	}];
+	return {
+		adminNamespace: "frontend",
+		adminDescriptor: () => descriptor,
+		adminEndpoints: () => endpoints
+	};
+}
+//#endregion
+export { buildFrontendStatus, createFrontendAdminApi };