nodefony 7.0.2 → 10.0.0-alpha.2

package/dist/types/syslog/sinks/FileSink.d.ts

@@ -0,0 +1,78 @@
+import { write as fsWrite } from "node:fs";
+import type { ILogSink } from "../Syslog.js";
+export interface FileSinkOptions {
+    /** Chemin du fichier de log (ouvert en append, créé si absent — dossier parent créé). */
+    path: string;
+    /** Octets max en attente avant DROP borné (anti-OOM). Défaut 4 MiB. */
+    maxPendingBytes?: number;
+    /**
+     * Écriture SYNCHRONE directe (`writeSync`) au lieu du buffer async. Sur un fd
+     * PAR worker (pas de fd partagé), le write sync local est µs et SANS contention
+     * d'inode → capte le gain cluster sans l'overhead du threadpool async (qui, sur
+     * un fichier local rapide, l'annule). Défaut `false` (async, pour sinks lents).
+     */
+    sync?: boolean;
+    /**
+     * Écriture asynchrone employée par le drain. Défaut `fs.write`.
+     *
+     * Injectable pour une seule raison : la remise du descripteur de fichier dépend
+     * d'une COURSE avec le pool de threads, et une course ne se provoque pas à
+     * volonté. En la pilotant depuis le banc, l'invariant « on ne rend jamais un
+     * descripteur sous une écriture en vol » devient une assertion au lieu d'un pari.
+     */
+    write?: typeof fsWrite;
+}
+/**
+ * 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.
+ */
+export declare class FileSink implements ILogSink {
+    #private;
+    readonly name = "file";
+    constructor(options: FileSinkOptions);
+    /** Lignes droppées (buffer saturé) — lu par une sonde, JAMAIS reloggé (récursion). */
+    get dropped(): number;
+    writeOut(s: string): void;
+    /**
+     * 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: string): void;
+    flushSync(): void;
+    /**
+     * 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(): void;
+}

package/dist/types/syslog/transports/BatchingHttpTransport.d.ts

@@ -0,0 +1,59 @@
+import type { ITransport } from "../../types/ITransport.js";
+import type Pdu from "../Pdu.js";
+/** Compteurs d'observabilité d'un transport batché (introspection / debug). */
+export interface BatchTransportStats {
+    /** Pdu jetés faute de place (queue saturée = destination trop lente / down). */
+    dropped: number;
+    /** Lots dont le push HTTP a échoué (best-effort : on n'empile pas indéfiniment). */
+    failedBatches: number;
+    /** Pdu actuellement en attente de flush. */
+    queued: number;
+}
+export interface BatchTransportOptions {
+    /** Flush dès que la queue atteint cette taille (coalescence). Défaut 100. */
+    batchSize?: number;
+    /** Flush périodique du reliquat (ms). Défaut 2000. */
+    flushIntervalMs?: number;
+    /**
+     * Plafond DUR de la queue (anti-OOM). Au-delà, les nouveaux logs sont DROP +
+     * comptés — on ne bloque JAMAIS le hot path ni ne fait exploser la RAM si la
+     * destination est lente/injoignable. Défaut 10000.
+     */
+    maxQueue?: number;
+}
+/**
+ * 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).
+ */
+export declare abstract class BatchingHttpTransport implements ITransport {
+    #private;
+    abstract readonly name: string;
+    constructor(options?: BatchTransportOptions);
+    /**
+     * 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: Pdu): Promise<void>;
+    /**
+     * Pousse un lot de Pdu vers la destination — implémenté par la sous-classe
+     * (format + endpoint spécifiques). Peut `throw` : la base catche et compte.
+     */
+    protected abstract flushBatch(batch: Pdu[]): Promise<void>;
+    /** Flush final explicite (arrêt gracieux). Best-effort, ne `throw` pas. */
+    close(): Promise<void>;
+    /** Compteurs d'observabilité (drop/échecs/queue). */
+    get stats(): BatchTransportStats;
+}

package/dist/types/syslog/transports/ConsoleTransport.d.ts

@@ -0,0 +1,8 @@
+import type { ITransport } from "../../types/ITransport.js";
+import type Pdu from "../Pdu.js";
+export declare class ConsoleTransport implements ITransport {
+    readonly name = "console";
+    private readonly pid;
+    constructor(pid?: string);
+    send(pdu: Pdu): Promise<void>;
+}

package/dist/types/syslog/transports/FileTransport.d.ts

@@ -0,0 +1,13 @@
+import type { ITransport } from "../../types/ITransport.js";
+import type Pdu from "../Pdu.js";
+export interface FileTransportOptions {
+    path: string;
+    format?: "json" | "text";
+}
+export declare class FileTransport implements ITransport {
+    readonly name = "file";
+    private readonly path;
+    private readonly format;
+    constructor(options: FileTransportOptions);
+    send(pdu: Pdu): Promise<void>;
+}

package/dist/types/syslog/transports/HttpTransport.d.ts

@@ -0,0 +1,15 @@
+import type { ITransport } from "../../types/ITransport.js";
+import type Pdu from "../Pdu.js";
+export interface HttpTransportOptions {
+    url: string;
+    headers?: Record<string, string>;
+    timeout?: number;
+}
+export declare class HttpTransport implements ITransport {
+    readonly name = "http";
+    private readonly url;
+    private readonly headers;
+    private readonly timeout;
+    constructor(options: HttpTransportOptions);
+    send(pdu: Pdu): Promise<void>;
+}

package/dist/types/syslog/transports/LokiTransport.d.ts

@@ -0,0 +1,45 @@
+import { BatchingHttpTransport } from "./BatchingHttpTransport.js";
+import type { BatchTransportOptions } from "./BatchingHttpTransport.js";
+import type { FetchLike } from "../httpFetch.js";
+import type Pdu from "../Pdu.js";
+export interface LokiTransportOptions extends BatchTransportOptions {
+    /** Base URL de Loki, ex. `http://127.0.0.1:3100` (sans le chemin d'API). */
+    url: string;
+    /**
+     * Labels de STREAM constants (basse cardinalité). Défaut `{ app: "nodefony" }`.
+     * ⚠️ Loki indexe les labels → garder PEU de labels et de faible cardinalité. Les
+     * labels dynamiques `severity`/`module`/`pid` sont ajoutés automatiquement (bornés).
+     * On n'y met JAMAIS `requestId` (haute cardinalité = explosion d'index) : il voyage
+     * dans la LIGNE JSON et se filtre côté query.
+     */
+    labels?: Record<string, string>;
+    /** Tenant multi-tenancy → header `X-Scope-OrgID`. Omis si absent. */
+    tenantId?: string;
+    /** Headers HTTP additionnels (auth proxy, etc.). */
+    headers?: Record<string, string>;
+    /** Timeout du push (ms). Défaut 5000. */
+    timeoutMs?: number;
+    /** Implémentation `fetch` (tests / proxy). Défaut : `fetch` global. */
+    fetchImpl?: FetchLike;
+}
+/**
+ * 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à).
+ */
+export declare class LokiTransport extends BatchingHttpTransport {
+    #private;
+    readonly name = "loki";
+    constructor(options: LokiTransportOptions);
+    protected flushBatch(batch: Pdu[]): Promise<void>;
+}

package/dist/types/syslog/transports/OpenSearchTransport.d.ts

@@ -0,0 +1,40 @@
+import { BatchingHttpTransport } from "./BatchingHttpTransport.js";
+import type { BatchTransportOptions } from "./BatchingHttpTransport.js";
+import type { FetchLike } from "../httpFetch.js";
+import type Pdu from "../Pdu.js";
+export interface OpenSearchTransportOptions extends BatchTransportOptions {
+    /** Base URL d'OpenSearch, ex. `http://127.0.0.1:9200` (sans chemin d'API). */
+    url: string;
+    /** Index cible (défaut `nodefony-logs`). Doit matcher celui du driver query. */
+    index?: string;
+    /** Utilisateur (auth basic) — prod avec plugin sécurité activé. */
+    username?: string;
+    /** Mot de passe (auth basic). */
+    password?: string;
+    /** Headers HTTP additionnels. */
+    headers?: Record<string, string>;
+    /** Timeout du bulk (ms). Défaut 5000. */
+    timeoutMs?: number;
+    /** Implémentation `fetch` (tests / proxy). Défaut : `fetch` global. */
+    fetchImpl?: FetchLike;
+}
+/**
+ * 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}.
+ */
+export declare class OpenSearchTransport extends BatchingHttpTransport {
+    #private;
+    readonly name = "opensearch";
+    constructor(options: OpenSearchTransportOptions);
+    protected flushBatch(batch: Pdu[]): Promise<void>;
+}

package/dist/types/syslog/transports/SyslogTransport.d.ts

@@ -0,0 +1,9 @@
+import type { ITransport } from "../../types/ITransport.js";
+import type Pdu from "../Pdu.js";
+import type Syslog from "../Syslog.js";
+export declare class SyslogTransport implements ITransport {
+    readonly name = "syslog";
+    private readonly target;
+    constructor(target: Syslog);
+    send(pdu: Pdu): Promise<void>;
+}

package/dist/types/syslog/transports/index.d.ts

@@ -0,0 +1,12 @@
+export { ConsoleTransport } from "./ConsoleTransport.js";
+export { FileTransport } from "./FileTransport.js";
+export type { FileTransportOptions } from "./FileTransport.js";
+export { HttpTransport } from "./HttpTransport.js";
+export type { HttpTransportOptions } from "./HttpTransport.js";
+export { SyslogTransport } from "./SyslogTransport.js";
+export { BatchingHttpTransport } from "./BatchingHttpTransport.js";
+export type { BatchTransportOptions, BatchTransportStats, } from "./BatchingHttpTransport.js";
+export { LokiTransport } from "./LokiTransport.js";
+export type { LokiTransportOptions } from "./LokiTransport.js";
+export { OpenSearchTransport } from "./OpenSearchTransport.js";
+export type { OpenSearchTransportOptions } from "./OpenSearchTransport.js";

package/dist/types/testing/index.d.ts

@@ -0,0 +1,197 @@
+import Container from "../Container.js";
+import Module from "../kernel/Module.js";
+import type { DefaultOptionsService } from "../Service.js";
+/**
+ * Outillage de TEST publié — ce qu'il faut pour éprouver un service SEUL.
+ *
+ * ## Le problème que ce sous-chemin résout
+ *
+ * Un service Nodefony reçoit un `Module` (`super(nom, module.container,
+ * module.notificationsCenter)`), et un `Module` réclame un `Kernel`. Éprouver
+ * la logique d'un service — un calcul de taxe, une règle métier — demandait
+ * donc de démarrer une application entière, ou de fabriquer soi-même un kernel
+ * de fortune avec un `as unknown as Kernel` que les règles du projet
+ * interdisent par ailleurs.
+ *
+ * Faute de cette porte, le réflexe observé est d'écrire un test de bout en bout
+ * : on lance le serveur et on tape en HTTP. Il éprouve la chaîne complète, il
+ * est lent, et il ne dit RIEN de l'isolation des responsabilités — la seule
+ * chose qu'on voulait vérifier.
+ *
+ * ## Ce qu'il ne fait pas
+ *
+ * Ce module ne démarre aucun kernel, n'ouvre aucun port, ne lit aucune
+ * configuration. Il rend un module JETABLE dont le seul rôle est de porter un
+ * conteneur et un bus d'événements — ce dont un service a besoin pour exister.
+ * Tout ce qui exige un kernel vivant (routes, firewall, ORM connecté) relève
+ * d'un test d'intégration, et cette porte ne prétend pas le remplacer.
+ *
+ * ⚠️ **La résolution PAR LE CONTENEUR n'est pas de la partie**, et c'est
+ * structurel : `@inject("XService")` passe par le singleton `Nodefony.getKernel()`
+ * (`injector.ts:169`), qui n'existe pas ici — l'injecteur fabriquerait alors un
+ * second exemplaire sans argument, et le constructeur casserait sur
+ * `module.container`. Ce n'est pas une limite gênante : **un test unitaire
+ * donne lui-même la dépendance**, ce que l'injection par constructeur permet
+ * précisément, et c'est ce qui autorise à y glisser un double.
+ *
+ * ```ts
+ * const app = createTestModule();
+ * const invoice = new InvoiceService(app, new TaxService(app));   // ✅
+ * const invoice = await app.addService(InvoiceService);           // ❌ exige un kernel
+ * ```
+ *
+ * @module
+ */
+export { nodefonyBin } from "../cli/nodefonyBin.js";
+/**
+ * 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.
+ */
+export declare function runningAppPort(root?: string): number;
+/** Réglages d'un module de test — tous facultatifs. */
+export interface ITestModuleOptions {
+    /** Nom du module (défaut `"test"`) — n'apparaît que dans les journaux. */
+    name?: string;
+    /**
+     * Racine du module. Doit contenir un `package.json` : `Module` le lit pour
+     * se situer. Défaut `process.cwd()`, qui convient à une suite lancée depuis
+     * la racine d'une application.
+     */
+    path?: string;
+    /**
+     * Options passées au module (`syslog`, `events`…).
+     *
+     * Rien n'est imposé par défaut : un module de test ne branche aucun
+     * transport, donc son journal reste muet sans qu'on ait à l'éteindre.
+     */
+    options?: DefaultOptionsService;
+    /**
+     * Conteneur à partager. Deux services construits sur le MÊME module partagent
+     * déjà le sien ; ne le passer que pour réutiliser un conteneur préparé
+     * (services simulés enregistrés à la main, par exemple).
+     */
+    container?: Container;
+}
+/**
+ * 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.
+ */
+export declare function createTestModule(settings?: ITestModuleOptions): Module;
+/** Réglages d'un exemplaire JETABLE — le port est le seul obligatoire. */
+export interface ISpareAppOptions {
+    /**
+     * Port HTTP de l'exemplaire — **imposé, jamais deviné**.
+     *
+     * L'exemplaire déjà démarré par le décor tient le port de l'application ;
+     * celui-ci doit en prendre un autre, et la sonde doit savoir à qui elle
+     * parle. Un port découvert après coup ferait retomber le test sur le premier
+     * serveur venu, exactement ce que {@link runningAppPort} refuse de faire.
+     */
+    port: number;
+    /** Port HTTPS, quand la configuration en ouvre un — même raison. */
+    httpsPort?: number;
+    /** Variables ajoutées à l'environnement de l'exemplaire. */
+    env?: NodeJS.ProcessEnv;
+    /** Racine de l'application ; le répertoire courant par défaut. */
+    root?: string;
+    /** Délai maximal d'attente de la première réponse, en ms (défaut 60 000). */
+    timeoutMs?: number;
+}
+/** Un exemplaire jetable, démarré et joignable. */
+export interface ISpareApp {
+    /** Port sur lequel il répond — celui qui a été demandé. */
+    port: number;
+    /** Tout ce qu'il a écrit sur ses deux flux jusqu'ici. */
+    output(): string;
+    /** L'arrête et REND à l'application son état d'exécution. */
+    stop(): Promise<void>;
+}
+/**
+ * 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.
+ */
+export declare function startSpareApp(options: ISpareAppOptions): Promise<ISpareApp>;