nodefony 7.0.2 → 10.0.0-alpha.2

package/dist/node/syslog/sinks/FileSink.js

@@ -0,0 +1,142 @@
+import { closeSync, mkdirSync, openSync, write, writeSync } from "node:fs";
+import { dirname } from "node:path";
+//#region src/syslog/sinks/FileSink.ts
+/**
+* Driver de sink fichier NON bloquant (LB.W). Écrit via `fs.write` async sur un
+* fd persistant ouvert en append (`"a"`) — **un fd PAR worker** (≠ stdout partagé
+* hérité du master), donc sans contention d'inode.
+*
+* ⚠️ **Le fd-par-worker n'est PAS le levier de performance** — c'est un garde-fou.
+* Le vrai levier est la **coalescence des writes** (nombre de syscalls) : ×19 à
+* ×25 selon les runs (2009 ms en 1 write/ligne → 81 ms en chunks). La contention
+* d'inode ne coûte ×3.2 à ×3.8 QUE dans le cas pathologique « 1 write par ligne » ;
+* **à coalescence égale elle disparaît** (84 vs 81 ms = dans la variance). Or le
+* ring/tick de `Syslog` coalesce DÉJÀ en amont : ce sink reçoit des chunks.
+* Rejouer : `node .claude/skills/nodefony-load-test/scripts/log-sink-contention.mjs`.
+*
+* Buffer applicatif borné + drop anti-OOM ; un seul write en vol → ordre FIFO
+* garanti ; flush SYNC de secours à l'`exit` (durabilité). Node-only.
+*/
+var FileSink = class {
+	name = "file";
+	#fd;
+	#maxPendingBytes;
+	#sync;
+	#pending = [];
+	#pendingBytes = 0;
+	#writing = false;
+	#inFlight = null;
+	#closed = false;
+	#fdClosed = false;
+	#dropped = 0;
+	#write;
+	constructor(options) {
+		mkdirSync(dirname(options.path), { recursive: true });
+		this.#fd = openSync(options.path, "a");
+		this.#maxPendingBytes = options.maxPendingBytes ?? 4194304;
+		this.#sync = options.sync ?? false;
+		this.#write = options.write ?? write;
+	}
+	/** Lignes droppées (buffer saturé) — lu par une sonde, JAMAIS reloggé (récursion). */
+	get dropped() {
+		return this.#dropped;
+	}
+	writeOut(s) {
+		if (this.#closed) return;
+		if (this.#sync) {
+			try {
+				writeSync(this.#fd, s);
+			} catch {}
+			return;
+		}
+		if (this.#pendingBytes >= this.#maxPendingBytes) {
+			this.#dropped++;
+			return;
+		}
+		this.#pending.push(s);
+		this.#pendingBytes += s.length;
+		if (!this.#writing) this.#drain();
+	}
+	/**
+	* stderr (sévérité ≤ 3 — ERROR/CRITIC/ALERT/EMERGENCY) → DURABLE même crash.
+	* Écrit en `writeSync` IMMÉDIAT hors buffer : un fatal n'est jamais perdu si le
+	* process est tué (SIGKILL/OOM) avant le drain async. En mode `sync`, `writeOut`
+	* fait déjà le `writeSync`. fd PAR worker + O_APPEND → write atomique ; best-effort
+	* sur erreur I/O (un logger ne throw jamais).
+	*
+	* ⚠️ Ordre : on NE ré-écrit PAS un chunk stdout async en vol (`#inFlight`, déjà
+	* soumis à `fs.write` → le ré-écrire = doublon kernel inévitable, non annulable).
+	* Conséquence assumée : un fatal peut atterrir juste AVANT un stdout encore en
+	* vol/bufferisé. Les timestamps par ligne (`HH:MM:SS.mmm`) font foi pour relire
+	* l'ordre causal. La durabilité du fatal prime sur l'ordre strict avec des stdout
+	* non-durables (perdus de toute façon au SIGKILL en mode async).
+	*/
+	writeErr(s) {
+		if (this.#closed) return;
+		if (this.#sync) {
+			this.writeOut(s);
+			return;
+		}
+		try {
+			writeSync(this.#fd, s);
+		} catch {}
+	}
+	#drain() {
+		if (this.#writing || this.#pending.length === 0) return;
+		this.#writing = true;
+		const chunk = this.#pending.join("");
+		this.#pending.length = 0;
+		this.#pendingBytes = 0;
+		this.#inFlight = chunk;
+		this.#write(this.#fd, chunk, (err) => {
+			this.#writing = false;
+			this.#inFlight = null;
+			if (this.#closed) {
+				this.#closeFd();
+				return;
+			}
+			if (!err) this.#drain();
+		});
+	}
+	/** Rend le descripteur au système, une seule fois. */
+	#closeFd() {
+		if (this.#fdClosed) return;
+		this.#fdClosed = true;
+		try {
+			closeSync(this.#fd);
+		} catch {}
+	}
+	flushSync() {
+		if (this.#closed) return;
+		const rest = (this.#inFlight ?? "") + this.#pending.join("");
+		this.#pending.length = 0;
+		this.#pendingBytes = 0;
+		this.#inFlight = null;
+		if (rest.length === 0) return;
+		try {
+			writeSync(this.#fd, rest);
+		} catch {}
+	}
+	/**
+	* Ferme le sink : plus rien n'est accepté, le pending part en SYNC, et le
+	* descripteur est rendu — mais **jamais sous une écriture en vol**.
+	*
+	* Un descripteur est un entier que le système réattribue au premier `open` venu.
+	* Le rendre pendant qu'une écriture asynchrone attend encore son tour dans le pool
+	* de threads, c'est la laisser atterrir dans le fichier — ou la socket — de
+	* quelqu'un d'autre, sans la moindre erreur visible. Le symptôme observé était une
+	* ligne d'un banc apparue en tête du fichier d'un autre ; il avait été pris pour un
+	* défaut d'isolation et « corrigé » par un dossier temporaire unique, d'où son
+	* retour. Quand une écriture est en vol, la remise est donc déléguée à son
+	* callback ({@link #closeFd}) — idempotente et sans attente pour l'appelant.
+	*/
+	close() {
+		if (this.#closed) return;
+		this.flushSync();
+		this.#closed = true;
+		if (this.#writing) return;
+		this.#closeFd();
+	}
+};
+//#endregion
+export { FileSink };

package/dist/node/syslog/transports/BatchingHttpTransport.js

@@ -0,0 +1,98 @@
+//#region src/syslog/transports/BatchingHttpTransport.ts
+/** Promesse résolue partagée — `send()` n'alloue pas une Promise par log. */
+const RESOLVED_VOID = Promise.resolve();
+/**
+* Base d'un transport de logs HTTP **batché** — généralise le pattern LB.W
+* (ring borné → drain coalescé → drop borné) à une destination réseau (Loki,
+* OpenSearch). Mutualise toute la mécanique de file/flush/drop/cleanup ; la
+* sous-classe n'implémente QUE {@link flushBatch} (formatage + push spécifiques).
+*
+* **Garanties hot path** : `send(pdu)` est O(1) non-bloquant (enqueue + arme un
+* timer `unref`), retourne une Promise résolue partagée (0 alloc/log), et ne
+* `throw` jamais — un push qui rate est compté, pas propagé au pipeline requête.
+* Coalescence : un POST par lot (≠ 1 requête HTTP par log = catastrophe réseau).
+*
+* **Durabilité best-effort** : flush sur `beforeExit` (le seul hook où l'on peut
+* encore faire de l'async proprement). PAS de handler `SIGTERM`/`SIGINT` — il
+* casserait le `Ctrl+C` (leçon LB.W). Un crash dur peut perdre le dernier lot :
+* acceptable pour une destination réseau (les logs y sont déjà best-effort), les
+* sévérités fatales restant écrites par le sink local synchrone (LB.W).
+*/
+var BatchingHttpTransport = class {
+	#queue = [];
+	#timer = null;
+	#flushing = false;
+	#dropped = 0;
+	#failedBatches = 0;
+	#exitHooked = false;
+	#batchSize;
+	#flushIntervalMs;
+	#maxQueue;
+	constructor(options = {}) {
+		this.#batchSize = options.batchSize ?? 100;
+		this.#flushIntervalMs = options.flushIntervalMs ?? 2e3;
+		this.#maxQueue = options.maxQueue ?? 1e4;
+	}
+	/**
+	* Enfile un log (O(1), non-bloquant). Flush immédiat si le lot est plein, sinon
+	* arme un timer `unref` pour drainer le reliquat. Queue saturée → DROP + compteur.
+	*/
+	send(pdu) {
+		if (!this.#exitHooked) {
+			this.#exitHooked = true;
+			process.once("beforeExit", () => {
+				this.#flush();
+			});
+		}
+		if (this.#queue.length >= this.#maxQueue) {
+			this.#dropped++;
+			return RESOLVED_VOID;
+		}
+		this.#queue.push(pdu);
+		if (this.#queue.length >= this.#batchSize) this.#flush();
+		else if (this.#timer === null) {
+			this.#timer = setTimeout(() => {
+				this.#timer = null;
+				this.#flush();
+			}, this.#flushIntervalMs);
+			if (typeof this.#timer.unref === "function") this.#timer.unref();
+		}
+		return RESOLVED_VOID;
+	}
+	/** Vide la queue par lots et pousse — réentrance protégée (un seul drain à la fois). */
+	async #flush() {
+		if (this.#flushing || this.#queue.length === 0) return;
+		if (this.#timer !== null) {
+			clearTimeout(this.#timer);
+			this.#timer = null;
+		}
+		this.#flushing = true;
+		const batch = this.#queue.splice(0, this.#queue.length);
+		try {
+			await this.flushBatch(batch);
+		} catch {
+			this.#failedBatches++;
+		} finally {
+			this.#flushing = false;
+		}
+		if (this.#queue.length >= this.#batchSize) this.#flush();
+	}
+	/** Flush final explicite (arrêt gracieux). Best-effort, ne `throw` pas. */
+	async close() {
+		if (this.#timer !== null) {
+			clearTimeout(this.#timer);
+			this.#timer = null;
+		}
+		await this.#flush();
+	}
+	/** Compteurs d'observabilité (drop/échecs/queue). */
+	get stats() {
+		return {
+			dropped: this.#dropped,
+			failedBatches: this.#failedBatches,
+			queued: this.#queue.length
+		};
+	}
+};
+//#endregion
+export { BatchingHttpTransport };

package/dist/node/syslog/transports/ConsoleTransport.js

@@ -0,0 +1,14 @@
+import Syslog from "../Syslog.js";
+//#region src/syslog/transports/ConsoleTransport.ts
+var ConsoleTransport = class {
+	name = "console";
+	pid;
+	constructor(pid = "") {
+		this.pid = pid;
+	}
+	async send(pdu) {
+		Syslog.normalizeLog(pdu, this.pid);
+	}
+};
+//#endregion
+export { ConsoleTransport };

package/dist/node/syslog/transports/FileTransport.js

@@ -0,0 +1,17 @@
+import { appendFile } from "node:fs/promises";
+//#region src/syslog/transports/FileTransport.ts
+var FileTransport = class {
+	name = "file";
+	path;
+	format;
+	constructor(options) {
+		this.path = options.path;
+		this.format = options.format ?? "json";
+	}
+	async send(pdu) {
+		const line = this.format === "json" ? JSON.stringify(pdu) + "\n" : `${new Date(pdu.timeStamp).toISOString()} ${pdu.severityName} ${pdu.msgid}: ${String(pdu.payload)}\n`;
+		await appendFile(this.path, line, "utf8");
+	}
+};
+//#endregion
+export { FileTransport };

package/dist/node/syslog/transports/HttpTransport.js

@@ -0,0 +1,44 @@
+import * as http$1 from "node:http";
+import * as https$1 from "node:https";
+//#region src/syslog/transports/HttpTransport.ts
+var HttpTransport = class {
+	name = "http";
+	url;
+	headers;
+	timeout;
+	constructor(options) {
+		this.url = new URL(options.url);
+		this.headers = options.headers ?? {};
+		this.timeout = options.timeout ?? 5e3;
+	}
+	send(pdu) {
+		return new Promise((resolve, reject) => {
+			const body = JSON.stringify(pdu);
+			const isHttps = this.url.protocol === "https:";
+			const options = {
+				hostname: this.url.hostname,
+				port: this.url.port || (isHttps ? 443 : 80),
+				path: this.url.pathname + this.url.search,
+				method: "POST",
+				headers: {
+					"Content-Type": "application/json",
+					"Content-Length": Buffer.byteLength(body),
+					...this.headers
+				}
+			};
+			const req = (isHttps ? https$1 : http$1).request(options, (res) => {
+				res.resume();
+				if (res.statusCode && res.statusCode >= 400) reject(/* @__PURE__ */ new Error(`HttpTransport: HTTP ${res.statusCode}`));
+				else resolve();
+			});
+			req.setTimeout(this.timeout, () => {
+				req.destroy(/* @__PURE__ */ new Error(`HttpTransport: timeout after ${this.timeout}ms`));
+			});
+			req.on("error", reject);
+			req.write(body);
+			req.end();
+		});
+	}
+};
+//#endregion
+export { HttpTransport };

package/dist/node/syslog/transports/LokiTransport.js

@@ -0,0 +1,80 @@
+import { stripTrailingSlashes } from "../../Tools.js";
+import { BatchingHttpTransport } from "./BatchingHttpTransport.js";
+import { pduToRecord } from "../drivers/ILogDriver.js";
+import { fetchWithTimeout, resolveFetch } from "../httpFetch.js";
+//#region src/syslog/transports/LokiTransport.ts
+/**
+* Transport de logs vers **Grafana Loki** (LB.4) — push HTTP **batché** sur
+* `POST /loki/api/v1/push`. Étend {@link BatchingHttpTransport} : la queue/flush/
+* drop/cleanup sont mutualisés ; ici on ne fait que **formater le lot** au schéma
+* Loki (streams + values) et l'envoyer.
+*
+* Modèle : 1 requête HTTP par lot (jamais par log). Les Pdu sont regroupés par jeu
+* de labels (`{...base, severity, module, pid}`), les valeurs triées par timestamp
+* croissant (exigence Loki), chaque ligne = le record wire `JSON.stringify(pduToRecord)`
+* (timestamp en **nanosecondes** = `ms·10⁶`). Le `requestId` reste DANS la ligne JSON
+* (pas un label) → corrélation full-stack via `| json` côté LogQL, sans alourdir l'index.
+*
+* Node-only (destination prod). Couplé au driver {@link createLokiLogDriver} (write↔read
+* cohérents : on pousse ici, on relit là).
+*/
+var LokiTransport = class extends BatchingHttpTransport {
+	name = "loki";
+	#pushUrl;
+	#baseLabels;
+	#headers;
+	#timeoutMs;
+	#fetch;
+	constructor(options) {
+		super(options);
+		this.#pushUrl = stripTrailingSlashes(options.url) + "/loki/api/v1/push";
+		this.#baseLabels = options.labels ?? { app: "nodefony" };
+		this.#headers = {
+			"content-type": "application/json",
+			...options.tenantId ? { "X-Scope-OrgID": options.tenantId } : {},
+			...options.headers
+		};
+		this.#timeoutMs = options.timeoutMs ?? 5e3;
+		this.#fetch = resolveFetch(options.fetchImpl);
+	}
+	async flushBatch(batch) {
+		const groups = /* @__PURE__ */ new Map();
+		for (const pdu of batch) {
+			const sev = pdu.severityName;
+			const mod = pdu.moduleName;
+			const pid = String(pdu.pid);
+			const key = `${sev}\0${mod}\0${pid}`;
+			let g = groups.get(key);
+			if (g === void 0) {
+				g = {
+					stream: {
+						...this.#baseLabels,
+						severity: sev,
+						module: mod,
+						pid
+					},
+					pdus: []
+				};
+				groups.set(key, g);
+			}
+			g.pdus.push(pdu);
+		}
+		const streams = [];
+		for (const g of groups.values()) {
+			g.pdus.sort((a, b) => a.timeStamp - b.timeStamp || a.uid - b.uid);
+			const values = g.pdus.map((p) => [`${p.timeStamp}000000`, JSON.stringify(pduToRecord(p))]);
+			streams.push({
+				stream: g.stream,
+				values
+			});
+		}
+		const res = await fetchWithTimeout(this.#fetch, this.#pushUrl, {
+			method: "POST",
+			headers: this.#headers,
+			body: JSON.stringify({ streams })
+		}, this.#timeoutMs);
+		if (!res.ok) throw new Error(`LokiTransport: push HTTP ${res.status}`);
+	}
+};
+//#endregion
+export { LokiTransport };

package/dist/node/syslog/transports/OpenSearchTransport.js

@@ -0,0 +1,53 @@
+import { stripTrailingSlashes } from "../../Tools.js";
+import { BatchingHttpTransport } from "./BatchingHttpTransport.js";
+import { pduToRecord } from "../drivers/ILogDriver.js";
+import { fetchWithTimeout, resolveFetch } from "../httpFetch.js";
+import { basicAuthHeader } from "../drivers/opensearchShared.js";
+//#region src/syslog/transports/OpenSearchTransport.ts
+/**
+* Transport de logs vers **OpenSearch** (LB.4) — indexation **batchée** via l'API
+* `POST /_bulk` (NDJSON). Étend {@link BatchingHttpTransport} (queue/flush/drop
+* mutualisés) ; ici on formate le lot au protocole bulk et on l'envoie.
+*
+* Protocole bulk : paires de lignes `{"index":{"_index":"…"}}\n` + `<document>\n`,
+* le corps DOIT se terminer par un newline (OpenSearch parse par `\n`). Le document
+* = record wire (`pduToRecord`) → mapping dynamique OpenSearch ; `requestId`/
+* `moduleName`/`severityName` deviennent des champs `text` + sous-champ `.keyword`
+* requêtables (cf {@link createOpenSearchLogDriver}). `timeStamp` (epoch ms) =
+* champ numérique → range/sort efficaces.
+*
+* Node-only (destination prod). Couplé au driver {@link createOpenSearchLogDriver}.
+*/
+var OpenSearchTransport = class extends BatchingHttpTransport {
+	name = "opensearch";
+	#bulkUrl;
+	#index;
+	#headers;
+	#timeoutMs;
+	#fetch;
+	constructor(options) {
+		super(options);
+		this.#bulkUrl = stripTrailingSlashes(options.url) + "/_bulk";
+		this.#index = options.index ?? "nodefony-logs";
+		this.#headers = {
+			"content-type": "application/x-ndjson",
+			...basicAuthHeader(options.username, options.password),
+			...options.headers
+		};
+		this.#timeoutMs = options.timeoutMs ?? 5e3;
+		this.#fetch = resolveFetch(options.fetchImpl);
+	}
+	async flushBatch(batch) {
+		const action = `{"index":{"_index":"${this.#index}"}}`;
+		let body = "";
+		for (const pdu of batch) body += action + "\n" + JSON.stringify(pduToRecord(pdu)) + "\n";
+		const res = await fetchWithTimeout(this.#fetch, this.#bulkUrl, {
+			method: "POST",
+			headers: this.#headers,
+			body
+		}, this.#timeoutMs);
+		if (!res.ok) throw new Error(`OpenSearchTransport: bulk HTTP ${res.status}`);
+	}
+};
+//#endregion
+export { OpenSearchTransport };

package/dist/node/syslog/transports/SyslogTransport.js

@@ -0,0 +1,13 @@
+//#region src/syslog/transports/SyslogTransport.ts
+var SyslogTransport = class {
+	name = "syslog";
+	target;
+	constructor(target) {
+		this.target = target;
+	}
+	async send(pdu) {
+		this.target.log(pdu);
+	}
+};
+//#endregion
+export { SyslogTransport };

package/dist/node/syslog/transports/index.js

@@ -0,0 +1,8 @@
+import { FileTransport } from "./FileTransport.js";
+import { BatchingHttpTransport } from "./BatchingHttpTransport.js";
+import { LokiTransport } from "./LokiTransport.js";
+import { OpenSearchTransport } from "./OpenSearchTransport.js";
+import { ConsoleTransport } from "./ConsoleTransport.js";
+import { HttpTransport } from "./HttpTransport.js";
+import { SyslogTransport } from "./SyslogTransport.js";
+export { BatchingHttpTransport, ConsoleTransport, FileTransport, HttpTransport, LokiTransport, OpenSearchTransport, SyslogTransport };

package/dist/node/testing/index.js

@@ -0,0 +1,190 @@
+import Container from "../Container.js";
+import { readRuntimeState, readinessStateFile, runtimeStateFile, signalProcessGroup } from "../service/dev/devProcess.js";
+import Module from "../kernel/Module.js";
+import { nodefonyBin } from "../cli/nodefonyBin.js";
+import { mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { once } from "node:events";
+import { spawn } from "node:child_process";
+//#region src/testing/index.ts
+/**
+* Port de l'application DÉMARRÉE, ou une erreur qui dit pourquoi on l'ignore.
+*
+* ## Pourquoi ce n'est pas `?? 5151`
+*
+* Un port de repli semble anodin — il ne l'est pas. Quand l'état d'exécution
+* est illisible (l'application n'a pas démarré, elle a démarré ailleurs, le
+* répertoire courant n'est pas sa racine), le repli envoie la suite interroger
+* **le premier serveur qui traîne sur cette machine**. Constaté : un serveur de
+* développement laissé ouvert par un autre projet a répondu `404` à tous les
+* cas, et la suite a accusé les routes de l'application au lieu de son décor.
+*
+* Un test qui parle au mauvais serveur ne se contente pas d'échouer : il rend
+* un verdict FAUX, et on cherche le défaut dans le code mesuré.
+*
+* Le port ne se devine donc pas. Il se lit — ou la suite s'arrête en disant
+* quoi vérifier.
+*
+* ```ts
+* import { runningAppPort } from "nodefony/testing";
+*
+* const res = await fetch(`http://127.0.0.1:${runningAppPort()}/api/hello`);
+* ```
+*
+* @param root - racine de l'application ; le répertoire courant par défaut,
+*   ce qui convient à une suite lancée depuis la racine du projet.
+* @returns le premier port sur lequel l'application écoute.
+* @throws Quand aucun état d'exécution n'est lisible, ou qu'il n'annonce aucun
+*   port — jamais un repli silencieux.
+*/
+function runningAppPort(root = process.cwd()) {
+	const port = readRuntimeState(root)?.ports?.[0];
+	if (typeof port !== "number") throw new Error(`aucune application Nodefony démarrée sous « ${root} » : l'état d'exécution est illisible ou n'annonce aucun port. Vérifie que le décor a bien lancé « nodefony production --detach --wait », et que la suite tourne depuis la racine de l'application. (Un port de repli ferait interroger un serveur ÉTRANGER, et le verdict porterait sur lui.)`);
+	return port;
+}
+/**
+* Un module JETABLE, prêt à porter un service dans un test.
+*
+* ```ts
+* import { createTestModule } from "nodefony/testing";
+* import TaxService from "../nodefony/service/TaxService";
+*
+* const tax = new TaxService(createTestModule());
+* expect(tax.rate()).toBe(0.2);
+* ```
+*
+* Deux services qui doivent se voir prennent le MÊME module : ils partagent
+* alors son conteneur, et `container.get("…")` résout comme à l'exécution.
+*
+* ```ts
+* const app = createTestModule();
+* const tax = new TaxService(app);
+* const invoice = new InvoiceService(app, tax);
+* ```
+*
+* @param settings - réglages facultatifs (cf {@link ITestModuleOptions}).
+* @returns un module utilisable comme argument de constructeur d'un service.
+*/
+function createTestModule(settings = {}) {
+	const kernel = { container: settings.container ?? new Container() };
+	return new Module(settings.name ?? "test", kernel, settings.path ?? process.cwd(), settings.options ?? {});
+}
+/**
+* Démarre un exemplaire JETABLE de l'application, dans un état choisi.
+*
+* ## À quoi ça sert
+*
+* Certaines choses ne s'observent que sur un processus qui démarre dans un état
+* précis : un schéma en retard qui retient la mise en service (`/readyz` rend
+* 503), une dépendance absente, un refus de démarrage. Le décor de la suite,
+* lui, a démarré l'application dans l'état NORMAL — et c'est ce qu'on veut : les
+* autres cas mesurent le fonctionnement.
+*
+* ## 🔴 Ce qu'il faut savoir, et qui ne se voit pas
+*
+* Un exemplaire Nodefony **publie ses ports** dans l'état d'exécution du projet
+* (`node_modules/.cache/nodefony/`), et cet état est un fichier UNIQUE par
+* racine d'application. Un second exemplaire lancé depuis le même dossier
+* l'écrase donc, et {@link runningAppPort} — que tous les autres cas
+* utilisent — se met à désigner le jetable, puis à lever une fois qu'il est
+* mort. Le défaut n'apparaît pas dans le cas qui l'a créé : il tombe sur le
+* SUIVANT, et accuse une route qui n'a rien fait.
+*
+* `stop()` restaure donc l'état d'exécution tel qu'il était avant le démarrage.
+* C'est la raison d'être de cette fonction, bien plus que le `spawn` qu'elle
+* fait à votre place.
+*
+* ```ts
+* const jetable = await startSpareApp({
+*   port: 5399,
+*   env: { NODE_ENV: "production", NF_DATABASE_URL: "sqlite:/tmp/vierge.db" },
+* });
+* try {
+*   const res = await fetch(`http://127.0.0.1:${jetable.port}/readyz`);
+*   assert.equal(res.status, 503);
+* } finally {
+*   await jetable.stop();
+* }
+* ```
+*
+* @param options - port imposé, environnement, racine.
+* @returns l'exemplaire, une fois qu'il répond.
+* @throws Si le processus meurt avant de répondre, ou si le délai expire — avec
+* ce qu'il a écrit, parce que c'est là que se trouve la cause.
+*/
+async function startSpareApp(options) {
+	const root = options.root ?? process.cwd();
+	const timeoutMs = options.timeoutMs ?? 6e4;
+	const state = readStateFiles(root);
+	const child = spawn(process.execPath, [nodefonyBin(), "production"], {
+		cwd: root,
+		detached: process.platform !== "win32",
+		env: {
+			...process.env,
+			NF_PORT: String(options.port),
+			...options.httpsPort === void 0 ? {} : { NF_PORT_HTTPS: String(options.httpsPort) },
+			...options.env
+		},
+		stdio: [
+			"ignore",
+			"pipe",
+			"pipe"
+		]
+	});
+	let output = "";
+	child.stdout?.on("data", (c) => output += c.toString());
+	child.stderr?.on("data", (c) => output += c.toString());
+	let exitCode = null;
+	child.on("exit", (code) => exitCode = code ?? -1);
+	const stop = async () => {
+		if (exitCode === null && typeof child.pid === "number") signalProcessGroup(child.pid, "SIGKILL");
+		await once(child, "exit").catch(() => void 0);
+		restoreStateFiles(state);
+	};
+	const deadline = Date.now() + timeoutMs;
+	for (;;) {
+		if (exitCode !== null) {
+			restoreStateFiles(state);
+			throw new Error(`l'exemplaire jetable est mort avant de répondre (code ${exitCode}) :\n${output.slice(-2e3)}`);
+		}
+		if (await fetch(`http://127.0.0.1:${options.port}/livez`).then((r) => r.ok).catch(() => false)) break;
+		if (Date.now() > deadline) {
+			await stop();
+			throw new Error(`l'exemplaire jetable n'a pas répondu sur le port ${options.port} en ${timeoutMs} ms :\n${output.slice(-2e3)}`);
+		}
+		await new Promise((r) => setTimeout(r, 250));
+	}
+	return {
+		port: options.port,
+		output: () => output,
+		stop
+	};
+}
+/** Relève les fichiers d'état qu'un exemplaire écrase en démarrant. */
+function readStateFiles(root) {
+	return [runtimeStateFile(root), readinessStateFile(root)].map((file) => {
+		try {
+			return {
+				file,
+				content: readFileSync(file, "utf8")
+			};
+		} catch {
+			return {
+				file,
+				content: null
+			};
+		}
+	});
+}
+/** Rend les fichiers d'état à ce qu'ils étaient — y compris leur absence. */
+function restoreStateFiles(state) {
+	for (const { file, content } of state) try {
+		if (content === null) rmSync(file, { force: true });
+		else {
+			mkdirSync(path.dirname(file), { recursive: true });
+			writeFileSync(file, content, "utf8");
+		}
+	} catch {}
+}
+//#endregion
+export { createTestModule, nodefonyBin, runningAppPort, startSpareApp };