nodefony 7.0.2 → 10.0.0-alpha.2

package/dist/types/service/cluster/richProcessProbe.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Sonde process **riche** d'un worker — le complément du lean {@link IProcessHealth}
+ * pour le drill-down (Phase 2). Ne contient QUE ce qui manque au lean : pression GC,
+ * répartition du heap V8, ressources actives, ELU active/idle (ms) et changements de
+ * contexte OS. Fusionné côté front avec le lean déjà présent dans le snapshot pod.
+ */
+export interface IProcessRich {
+    /** Pression GC sur l'intervalle (cycles, pause totale ms, majeurs/mineurs). */
+    gc: {
+        count: number;
+        pauseMs: number;
+        major: number;
+        minor: number;
+    };
+    /** Répartition mémoire V8 par espace (new/old/code/large_object…), octets. */
+    heapSpaces: {
+        name: string;
+        used: number;
+        size: number;
+    }[];
+    /** Ressources actives qui tiennent la boucle, total + par type. */
+    handles: {
+        total: number;
+        byType: Record<string, number>;
+    };
+    /** Saturation de la boucle sur l'intervalle (ms actifs / idle ; utilization est dans le lean). */
+    elu: {
+        active: number;
+        idle: number;
+    };
+    /** Changements de contexte OS sur l'intervalle (volontaires = cède, involontaires = préempté). */
+    ctx: {
+        voluntary: number;
+        involuntary: number;
+    };
+    /** Load average système (1/5/15 min). */
+    loadavg: [number, number, number];
+    /** Limite de heap V8 du process (octets) — constante. */
+    heapLimit: number;
+    /** Nombre de cœurs vus par le process — constante. */
+    cpuCount: number;
+    /** Horodatage de la mesure. */
+    ts: number;
+}
+/**
+ * Sonde process **riche stateful** d'un worker — calcule les métriques par INTERVALLE
+ * (GC, ELU active/idle, changements de contexte sont des deltas entre deux `read()`).
+ * Une instance par process worker, **lazy & opt-in** : créée seulement quand un drill
+ * est actif sur ce worker (« on paie ce qu'on regarde »).
+ *
+ * Perf (worker uniquement, JAMAIS hot path request) : l'observer GC n'est attaché qu'à
+ * {@link enable} (1ᵉʳ `read()` sinon) et **détaché à {@link disable}** (aucun listener
+ * orphelin). Les sondes lourdes (`getHeapSpaceStatistics`, `getActiveResourcesInfo`,
+ * `getrusage`) ne tournent qu'au `read()` (au tick de report, ≥ 1 s). SERVEUR uniquement
+ * (`node:v8`/`node:perf_hooks`/`node:os`) → non importé par le bundle client.
+ *
+ * Logique portée de `createStatsTicker` (`@nodefony/studio`) en classe réutilisable :
+ * source unique de la sonde process riche, partagée par le drill cluster et la
+ * supervision mono-process.
+ */
+export declare class RichProcessProbe {
+    #private;
+    /**
+     * Attache l'observer GC et réinitialise les baselines de delta (ELU/ctx). Idempotent.
+     * Appelé automatiquement au 1ᵉʳ `read()` ; explicite pour démarrer la collecte GC tôt.
+     */
+    enable(): void;
+    /**
+     * Lit la sonde riche courante (deltas depuis le dernier `read()`, snapshots heap/handles).
+     *
+     * @returns {@link IProcessRich} prêt à être joint au report du worker drillé.
+     */
+    read(): IProcessRich;
+    /** Détache l'observer GC (fin du drill / arrêt du worker). Idempotent. */
+    disable(): void;
+}
+export default RichProcessProbe;

package/dist/types/service/cluster/topology.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Réglage de topologie de l'application — la « molette » côté DevOps (remplace le
+ * rôle de `instances` dans l'ancien `pm2.config.ts`, retiré en cloud-native).
+ *
+ * - `1` — VRAI mono-process : aucune machinerie cluster (pas de master, pas de
+ *   backplane, pas d'agrégateur). C'est le défaut cloud-native (1 process = 1 pod,
+ *   scaling horizontal délégué à l'orchestrateur k8s/HPA).
+ * - `"auto"` — nb de workers résolu **cgroup-aware** (quota CPU du conteneur, jamais
+ *   `os.cpus()`). Pour une grosse VM / VPS / gros pod sans orchestrateur.
+ * - `<N>` — nombre explicite de workers.
+ */
+export type WorkersSetting = number | "auto";
+/**
+ * Bloc `cluster` de la config app — lisible **sans kernel** (le master fork les
+ * workers AVANT de booter le moindre Kernel : il doit donc lire ce réglage seul).
+ * Doit rester kernel-free pour pouvoir être importé directement par le master.
+ */
+export interface IClusterConfig {
+    /** Nombre de workers / topologie. Défaut : `1` (mono-process cloud-native). */
+    workers: WorkersSetting;
+}
+/** D'où vient la valeur `workers` retenue — pour le log de diagnostic au boot. */
+export type TopologySource = "flag" | "env" | "config" | "default";
+/** Résultat résolu de la topologie : nombre de workers + provenance. */
+export interface Topology {
+    /** Nombre de workers à forker. `1` = mono-process (aucune machinerie cluster). */
+    workers: number;
+    /** Provenance de la valeur (CLI `--workers`, env, config app, défaut). */
+    source: TopologySource;
+}
+/** Seams de {@link resolveTopology} — tous injectables (résolution pure, testable sans FS). */
+export interface ResolveTopologyOptions {
+    /** CLI `--workers <n|auto>` (chaîne Commander). Priorité MAX (override opérateur). */
+    flag?: string;
+    /** Override `NF_WORKERS` (Docker/k8s). Défaut : lecture de `process.env`. */
+    env?: string;
+    /** Valeur de la config app `cluster.workers` (le knob DevOps par défaut). */
+    config?: WorkersSetting;
+}
+/**
+ * Résout LA topologie de lancement — source unique de vérité pour « combien de
+ * workers ». Ordre de priorité (premier défini gagne) :
+ *
+ * 1. **CLI `--workers`** — override explicite de l'opérateur (jamais borné).
+ * 2. **env `NF_WORKERS`** — override déploiement (Docker/k8s, sans éditer de fichier).
+ * 3. **config app `cluster.workers`** — le knob DevOps par défaut (remplace PM2 `instances`).
+ * 4. **défaut `1`** — mono-process cloud-native.
+ *
+ * @returns `{ workers, source }` — `workers >= 1` toujours.
+ */
+export declare function resolveTopology(opts?: ResolveTopologyOptions): Topology;
+/**
+ * Lit le bloc `cluster` de la config app de façon **standalone** (best-effort), sans
+ * booter de Kernel — c'est tout ce dont le master a besoin pour décider du fork.
+ *
+ * Importe le fichier compilé `dist/nodefony/config/cluster/cluster.config.js` sous
+ * `appPath` (défaut `process.cwd()`, = `Kernel.path`). Toute erreur (fichier absent,
+ * import KO) → `null` : la résolution retombe alors sur CLI/env/défaut. Le fichier
+ * config DOIT rester kernel-free pour être importable ici.
+ *
+ * @param appPath - racine de l'app (défaut `process.cwd()`).
+ * @returns la valeur `cluster.workers`, ou `null` si introuvable.
+ */
+export declare function loadClusterConfig(appPath?: string): Promise<WorkersSetting | null>;

package/dist/types/service/dev/BootReporter.d.ts

@@ -0,0 +1,67 @@
+import type Kernel from "../../kernel/Kernel.js";
+/**
+ * Vue minimale d'une zone du firewall (`firewall.describe().zones`), résolue
+ * par duck-typing — le core n'importe jamais @nodefony/security.
+ */
+export interface FirewallZoneView {
+    readonly name: string;
+    readonly pattern: string;
+    readonly security?: boolean;
+    readonly authenticators?: ReadonlyArray<string>;
+    readonly allowsAnonymous?: boolean;
+}
+/**
+ * Pattern de zone LISIBLE : `describe()` remonte `RegExp.source`, où V8 échappe
+ * les slashes (`^\/nodefony\/…`) — on dé-échappe pour l'affichage ET pour le
+ * classement par namespace (un `startsWith("^/nodefony")` sur la source brute
+ * ne matcherait jamais — bug vécu au premier boot réel).
+ */
+export declare function cleanZonePattern(pattern: string): string;
+/**
+ * `true` si la zone vit dans le namespace réservé `/nodefony` → déclarée par
+ * `@nodefony/framework` (les aires data plane admin). L'inférence par pattern
+ * est fiable PAR CONVENTION : le routage `/nodefony` est réservé au framework
+ * (règle figée), aucune app/module tiers n'y monte d'aire.
+ */
+export declare function isFrameworkZone(z: FirewallZoneView): boolean;
+/**
+ * Tableau ANSI des zones firewall (ZONE/MODULE/PATTERN/AUTH/ACCÈS) — même
+ * gabarit que le tableau process du bilan (`renderProcessTable`). MODULE = qui
+ * déclare l'aire (`framework` pour le data plane `/nodefony`, `app` pour les
+ * zones du `nodefony.config.ts`). ACCÈS résume la politique effective :
+ * `public` (security:false), `anonyme OK` (authenticator anonymous dans la
+ * chaîne — jamais bloquant, identité résolue si présente) ou `protégé`
+ * (preuve exigée, 401 sinon). Zones applicatives en vert, aires framework en dim.
+ */
+export declare function renderZoneTable(lines: string[], zones: ReadonlyArray<FirewallZoneView>, indent?: string): void;
+/**
+ * Affichage « boot de rêve » du serveur en développement : une checklist animée
+ * (spinner + `✓`/`✗` par phase de boot) à la place du mur de logs `INFO`/`MODULE ADD`.
+ *
+ * **Dev-only** : instancié uniquement par `DevCommand`, côté enfant supervisé
+ * (`NF_DEV_CHILD=1`). En prod/cluster : jamais (logs structurés cloud-native).
+ *
+ * **Backplane-safe** : le spinner s'écrit DIRECTEMENT sur `process.stdout`, jamais via
+ * le Syslog. Le mute pendant le boot = {@link Syslog.setSinkEnabled} (coupe le sink
+ * texte écran) ; les transports d'écriture (`_transports` : file/cluster/loki) ET le
+ * ring buffer reçoivent TOUS les logs → rien perdu, le Log Backplane intact.
+ *
+ * Trois modes (tous dev-only) :
+ * - **TTY normal** : spinner animé + console mutée (logs → buffer/backplane).
+ * - **`--debug`** : pas d'animation, pas de mute → marqueurs `✓` de phase entre les logs
+ *   bruts complets (structure sans rien cacher).
+ * - **non-TTY** (CI/redirection) : marqueurs statiques, zéro séquence `\r`.
+ */
+declare class BootReporter {
+    #private;
+    constructor(kernel: Kernel, opts: {
+        debug: boolean;
+        tty: boolean;
+    });
+    /**
+     * Branche les hooks de phase sur le Kernel + démarre l'affichage.
+     * À appeler depuis `DevCommand.onKernelPreStart` (après le splash, avant `loadApp`).
+     */
+    attach(): void;
+}
+export default BootReporter;

package/dist/types/service/dev/DevSupervisor.d.ts

@@ -0,0 +1,117 @@
+import type { EventEmitter } from "node:events";
+/** Options du superviseur de dev. */
+export interface DevSupervisorOptions {
+    /** Racine du projet (cwd). */
+    readonly cwd: string;
+    /** Dossiers/fichiers backend surveillés (relatifs au cwd). */
+    readonly paths?: readonly string[];
+    /** Délai d'anti-rebond avant rebuild+restart (ms). */
+    readonly debounceMs?: number;
+    /** Variable d'env injectée dans l'enfant pour le distinguer du parent. */
+    readonly childEnvKey?: string;
+    /**
+     * Ports serveur à attendre **libres** avant de relancer l'enfant (évite
+     * `EADDRINUSE` au restart). Défaut : `[5151, 5152]` (HTTP/HTTPS Nodefony) ou
+     * `NF_DEV_PORTS` (liste séparée par des virgules). Les ports Vite ne sont
+     * pas listés : l'arrêt emporte l'arbre (Vite compris) et chaque instance a son
+     * propre port-retry au redémarrage.
+     */
+    readonly ports?: readonly number[];
+}
+/**
+ * Ce chemin doit-il être IGNORÉ par le watch des sources backend ?
+ *
+ * Le superviseur ne surveille que le **serveur** : les sources client ont leur
+ * propre boucle (HMR Vite), les artefacts (`dist`) sont produits par le build, et
+ * les tests ne font pas partie du runtime.
+ *
+ * ⚠️ Le piège que cette fonction referme : « frontend » est un RÔLE (le dossier
+ * des sources SPA d'un module : `studio/frontend/`, `modules/x/frontend/`) **et**
+ * un NOM DE PAQUET (`@nodefony/frontend`, le builder Vite — qui est du code
+ * SERVEUR). Ignorer tout segment nommé `frontend` rendait le watch AVEUGLE sur
+ * tout ce paquet : on l'éditait, il ne se passait rien, jamais. On n'exclut donc
+ * le dossier `frontend` que lorsqu'il n'est PAS le paquet `@nodefony/frontend`.
+ *
+ * Fonction PURE (pas de fs) → testable sans chokidar ni serveur.
+ *
+ * @param p - chemin du fichier ou dossier (relatif au projet, ou absolu).
+ * @param isFile - `true` si l'entrée est un fichier (un non-`.ts` est alors ignoré).
+ */
+export declare function isIgnoredWatchPath(p: string, isFile?: boolean): boolean;
+/**
+ * Applique {@link isIgnoredWatchPath} à une entrée telle que chokidar la fournit —
+ * c'est-à-dire en chemin **absolu**.
+ *
+ * ⚠️ Le piège que cette fonction referme : les segments qui désignent un dossier de
+ * travail (`tmp`, `var`) sont des noms ORDINAIRES ailleurs. Sur macOS, `TMPDIR` vaut
+ * `/var/folders/…` — une application lancée depuis un dossier temporaire (ce que font
+ * nos propres bancs de scaffold) verrait donc CHAQUE entrée rejetée, et le watch
+ * deviendrait aveugle sans un mot. La règle ne vaut que **dans** le projet : on
+ * relativise au répertoire du projet AVANT de filtrer.
+ *
+ * @param cwd - racine du projet surveillé.
+ * @param p - chemin fourni par le watcher (absolu ou déjà relatif).
+ * @param isFile - `true` si l'entrée est un fichier.
+ */
+export declare function shouldIgnoreWatchEntry(cwd: string, p: string, isFile?: boolean): boolean;
+/**
+ * Rend une erreur du watcher NON FATALE : la signale et poursuit la surveillance.
+ *
+ * Le watch est un **capteur**, pas une garantie : un dossier qui disparaît pendant
+ * son scan, un lien symbolique cassé, une permission refusée sont des faits du
+ * système de fichiers, pas des fautes du superviseur. Sans écouteur `error`, Node
+ * convertit l'événement en exception non rattrapée — et le serveur de développement
+ * entier meurt d'un incident d'observation.
+ *
+ * ⚠️ **Portée exacte** : ce garde ne couvre que ce que chokidar émet LUI-MÊME
+ * (`_handleError`, dont l'`EPERM` de Windows). Une erreur levée par le flux de
+ * parcours interne ne passe PAS par le watcher — chokidar branche `close` et `end`
+ * sur ses streams, jamais `error` — et reste donc fatale. C'est pourquoi le cas vécu
+ * en intégration continue (la suite de tests supprimait `src/nodefony/tmp/copied`
+ * pendant qu'un serveur détaché tournait ; le parcours rendait `EBUSY` et le process
+ * sortait en 1) se referme en amont, en ne DESCENDANT pas dans les dossiers de
+ * travail — cf {@link isIgnoredWatchPath}, et non ici.
+ *
+ * Le prix d'une erreur avalée est réel — le watch peut avoir perdu une branche —
+ * donc on la DIT : un rechargement qui ne part plus sans un mot est un mystère.
+ *
+ * @param watcher - l'émetteur à protéger (le `FSWatcher` de chokidar en production).
+ * @param log - reçoit le message à journaliser.
+ */
+export declare function attachWatcherErrorGuard(watcher: EventEmitter, log: (message: string) => void): void;
+/**
+ * Superviseur de développement « auto-restart » (modèle nodemon, cloud-native :
+ * le process serveur est jetable).
+ *
+ * Topologie : ce process **parent** ne boote PAS le kernel applicatif — il
+ * `spawn` le serveur dans un process **enfant** (même commande + variable d'env
+ * `NF_DEV_CHILD=1`), surveille les sources **backend** et, à chaque
+ * changement, rebuild puis **redémarre l'enfant**.
+ *
+ * Le restart doit emporter l'**arbre** de l'enfant — lui et les instances Vite du
+ * `ViteProcessSupervisor` — sans quoi chaque sauvegarde laisse un Vite orphelin
+ * retenant son port. Deux grammaires y mènent, une par famille de système, et une
+ * seule implémentation les porte (`signalProcessGroup`) : en POSIX l'enfant est
+ * spawné **detached**, donc leader d'un groupe que `process.kill(-pid, …)` emporte
+ * d'un coup ; sous Windows, où les groupes POSIX n'existent pas, il est au contraire
+ * **rattaché** pour que `taskkill /T` puisse descendre la filiation. Avant chaque
+ * relance, le superviseur attend que les ports serveur soient libres
+ * (anti-`EADDRINUSE`) et retente de façon bornée si l'enfant crashe immédiatement.
+ *
+ * Pourquoi pas de HMR backend : Node ne décharge pas un module ESM déjà importé →
+ * un re-bundle du `dist/` ne rechargerait rien. Le restart de process est le seul
+ * rechargement backend fiable. Le **frontend** (Vite) garde son HMR : le dossier
+ * `frontend/` est exclu de la surveillance → une modif front ne redémarre pas le
+ * serveur.
+ */
+export declare class DevSupervisor {
+    #private;
+    constructor(options: DevSupervisorOptions);
+    /**
+     * Démarre le superviseur : revendique le verrou single-instance (tue tout
+     * superviseur précédent resté en vie), branche les signaux d'arrêt, attend les
+     * ports libres puis lance l'enfant et la surveillance.
+     */
+    start(): Promise<void>;
+}
+export default DevSupervisor;

package/dist/types/service/dev/bootVerdict.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Ce qu'une sonde peut rendre — et la distinction qui évite d'attendre pour rien.
+ *
+ * `"booting"` et `"unreachable"` valent tous deux « pas de verdict », mais PAS la même
+ * conduite : le premier s'attend (le boot finira), le second ne s'attendra jamais (rien
+ * ne répond en clair sur ce port, et rien n'y répondra). Les confondre coûtait la
+ * fenêtre de stabilisation ENTIÈRE à chaque démarrage d'une application sans route de
+ * santé joignable — un prix payé par tous pour une information qui ne viendra pas.
+ */
+export type BootProbe = boolean | "booting" | "unreachable";
+/**
+ * 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).
+ */
+export declare function probeBootDegraded(port: number | undefined, deps?: {
+    /** Récupère le corps de `livez` ; rend `null` sur tout échec. */
+    readonly fetchLivez?: (port: number) => Promise<string | null>;
+}): Promise<BootProbe>;
+/**
+ * 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.
+ */
+export declare function waitBootVerdict(port: number | undefined, settleMs: number, deps?: {
+    readonly fetchLivez?: (port: number) => Promise<string | null>;
+    readonly now?: () => number;
+    readonly delay?: (ms: number) => Promise<void>;
+    /** Interrompt l'attente (redémarrage, arrêt) — le verdict devient sans objet. */
+    readonly aborted?: () => boolean;
+}): Promise<boolean | null>;
+/**
+ * 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.
+ */
+export declare function extractSkippedModules(journal: string): string[];
+/** Ce qu'un runtime dit de sa DISPONIBILITÉ — « peut-il servir maintenant ? ». */
+export interface IReadinessProbe {
+    /** `true` = le pod peut servir (boot fini ET rien ne le retient). */
+    readonly ready: boolean;
+    /** Nombre de composants qui retiennent la mise en service (0 = aucun). */
+    readonly blocked: number;
+    /**
+     * QUI retient, et pourquoi — `undefined` quand le détail n'est pas
+     * disponible ou ne CONCORDE pas avec le compte que le runtime vient de
+     * rendre.
+     *
+     * Le compte vient du runtime interrogé à l'instant ; le détail vient du
+     * fichier que le serveur publie. **Deux sources doivent concorder pour qu'on
+     * nomme** : un fichier en retard d'un cycle désignerait un contributeur déjà
+     * libéré, et l'on chercherait une cause disparue — pire que de ne rien
+     * nommer.
+     */
+    readonly blockedBy?: readonly {
+        name: string;
+        reason?: string;
+    }[];
+}
+/**
+ * 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.
+ */
+export declare function probeReadiness(port: number | undefined, deps?: {
+    readonly fetchLivez?: (port: number) => Promise<string | null>;
+}): Promise<IReadinessProbe | null>;

package/dist/types/service/dev/detachedStart.d.ts

@@ -0,0 +1,164 @@
+import { type PortState } from "./devProcess.js";
+/**
+ * Lancement DÉTACHÉ d'un runtime Nodefony (`nodefony development --detach`) —
+ * absorbe l'expérience du script `start.sh` du skill dans le framework :
+ * spawn détaché + attente de readiness + health check + code de sortie sémantique.
+ *
+ * Pur outillage de process (spawn + sonde ports + log file) : AUCUN boot kernel dans
+ * le process appelant → exécuté par le fast-path standalone de `CliKernel.start`
+ * (même famille que `status`/`stop`). Le kill préalable n'est PAS dupliqué ici :
+ * le child le porte nativement (`#claimSingleInstance` dev balaie les résiduels ;
+ * prod/cluster refuse fail-loud un runtime concurrent).
+ *
+ * Fail-fast SANS heuristique fragile : contrairement au script (détection « log figé
+ * 20 s » → faux TIMEOUT pendant un rebuild turbo légitime), on n'observe que des
+ * signaux SÛRS — process mort (exit code) OU plafond global dépassé. Un boot lent
+ * qui rebuilde reste un boot sain tant que le process vit.
+ */
+/** Options du détacheur, parsées d'argv (cf {@link parseDetachArgs}). */
+export interface DetachedStartOptions {
+    /** Ligne de spawn complète — injectable pour les tests. */
+    spawnCmd: string;
+    spawnArgs: string[];
+    /** Répertoire de travail du child (défaut `process.cwd()`). */
+    cwd?: string;
+    /** Fichier de log du runtime détaché (stdout+stderr du child). */
+    logFile: string;
+    /** Plafond d'attente de readiness en secondes (défaut 120). */
+    waitSec?: number;
+    /** Ports dont l'écoute signe la readiness (défaut `defaultDevPorts()`). */
+    ports?: number[];
+    /** Path d'un GET de santé post-listen (best-effort, jamais bloquant). */
+    healthPath?: string;
+    /**
+     * Déclarer prêt un runtime dont le boot est DÉGRADÉ (cf `ParsedDetachArgs`).
+     * Défaut `false` : un module déclaré et non chargé est un échec de readiness.
+     */
+    allowDegraded?: boolean;
+    /** Callback de progression (une ligne ~toutes les 5 s). */
+    onProgress?: (msg: string) => void;
+    /** Variables d'env additionnelles pour le child. */
+    env?: Record<string, string>;
+}
+/** Résultat du lancement détaché. */
+export interface DetachedStartResult {
+    ok: boolean;
+    /** PID du process détaché (leader de groupe), `null` si le spawn a échoué. */
+    pid: number | null;
+    /** Code de sortie sémantique pour le process appelant (sysexits). */
+    exitCode: number;
+    /** État final des ports sondés. */
+    ports: PortState[];
+    logFile: string;
+    /** Résultat du health check (`"200"`, `"skipped (…)"`), absent si non demandé. */
+    health?: string;
+    /**
+     * Ports DEMANDÉS par la config quand l'app a dû glisser ailleurs
+     * (`servers.portPolicy: "auto"`), absent sinon. Un décalage tu en silence est la
+     * cause n°1 des « tout répond 404 » : le client garde le port de sa config et
+     * tombe sur le serveur du voisin, qui lui répond très bien — mais autre chose.
+     */
+    desiredPorts?: number[];
+    /**
+     * Modules que le boot a IGNORÉS (`nom — motif`), lus dans le journal du runtime.
+     * Renseigné quand la readiness est refusée pour boot dégradé : sans ces noms, le
+     * refus serait un « dégradé » sans coupable, aussi muet que le silence qu'il
+     * remplace.
+     */
+    modulesSkipped?: string[];
+    /** Cause de l'échec (`ok: false`) — diagnostic humain. */
+    reason?: string;
+    /** Dernières lignes du log (strip ANSI) pour le diagnostic d'échec. */
+    logTail?: string[];
+}
+/** Options des flags détacheur reconnues dans argv. */
+export interface ParsedDetachArgs {
+    detach: boolean;
+    waitSec: number;
+    healthPath?: string;
+    logFile?: string;
+    /**
+     * Accepter un boot DÉGRADÉ (un module du manifeste ignoré) comme « prêt ».
+     *
+     * Le défaut est NON, et c'est le contrat même de la readiness : une application
+     * amputée d'un module qu'elle DÉCLARE ne peut pas servir ce qu'on lui demandera,
+     * et un orchestrateur ne doit pas lui envoyer de trafic. Le drapeau existe pour
+     * qui l'assume — un module optionnel absent d'un décor donné — mais la décision
+     * s'écrit alors, elle ne se subit plus en silence.
+     */
+    allowDegraded: boolean;
+    /** argv à relayer au child (flags détacheur STRIPPÉS — anti-récursion). */
+    relayArgs: string[];
+}
+/** Marqueur env anti-récursion : posé sur le child pour couper tout re-détachement. */
+export declare 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.
+ */
+export declare function childEnv(parent: NodeJS.ProcessEnv, extra?: Record<string, string>): NodeJS.ProcessEnv;
+/**
+ * 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.
+ */
+export declare function childExecArgv(parentExecArgv: string[]): string[];
+/**
+ * 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)`.
+ */
+export declare function parseDetachArgs(args: string[]): ParsedDetachArgs;
+/** `true` si l'invocation demande un lancement détaché (et n'est PAS déjà le child). */
+export declare function isDetachRequested(args: string[]): boolean;
+/**
+ * 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`.
+ */
+export declare function launchDetached(opts: DetachedStartOptions): Promise<DetachedStartResult>;
+/**
+ * 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`).
+ */
+export declare function runDetachedStart(argv: string[]): Promise<number>;