nodefony 7.0.2 → 10.0.0-alpha.2

package/dist/node/syslog/drivers/builtinLogDrivers.js

@@ -0,0 +1,114 @@
+import { registerLogDriverFactory } from "./logDriverRegistry.js";
+import { FileTransport } from "../transports/FileTransport.js";
+import { LokiTransport } from "../transports/LokiTransport.js";
+import { OpenSearchTransport } from "../transports/OpenSearchTransport.js";
+import { createMemoryLogDriver } from "./MemoryLogDriver.js";
+import { createFileLogDriver } from "./FileLogDriver.js";
+import { createClusterFileLogDriver } from "./ClusterFileLogDriver.js";
+import { createLokiLogDriver } from "./LokiLogDriver.js";
+import { createOpenSearchLogDriver } from "./OpenSearchLogDriver.js";
+import path from "node:path";
+//#region src/syslog/drivers/builtinLogDrivers.ts
+/** Chemin du JSONL queryable de CE worker (write↔read pour file/cluster-file). */
+function jsonlPath(ctx) {
+	return ctx.logCfg?.queryFile?.path ?? path.join(ctx.logDir, `nodefony-${ctx.pid}.jsonl`);
+}
+/**
+* Résout le driver de relecture EFFECTIF depuis la valeur demandée, le mode de
+* lancement et les destinations distantes déclarées. La sentinelle `"auto"`
+* (défaut du framework) S'ADAPTE :
+* 1. une destination distante déclarée (URL loki/opensearch — infra logs) impose
+*    son driver : l'URL ⇒ le driver, un seul knob. Les DEUX déclarées sans choix
+*    explicite = throw (fail-loud : pas d'arbitrage silencieux entre deux
+*    destinations de relecture) ;
+* 2. sinon un worker de cluster (process forké) relit via `cluster-file` — vue
+*    UNIFIÉE agrégeant les JSONL de tous les workers — là où `memory` (ring
+*    per-worker) ne montrerait qu'un worker ; un mono-process reste sur
+*    `memory` (0 I/O).
+*
+* On n'intervient QUE sur le défaut : toute valeur EXPLICITE (`memory`, `file`,
+* `loki`, …) est une surcharge de l'opérateur → respectée telle quelle, jamais
+* réécrite (principe de moindre surprise, 12-factor).
+*
+* @param requested - `log.queryDriver` résolu (config app/env) ; `undefined` ou
+*   `"auto"` = laisser le framework décider.
+* @param isWorker - process forké d'un cluster (`cluster.isWorker`).
+* @param urls - URLs des destinations distantes déclarées (config `log.loki`/
+*   `log.opensearch`, montées depuis l'infra logs).
+* @returns nom du driver de relecture à activer + monter.
+* @throws Error si les deux URLs sont déclarées sans `queryDriver` explicite.
+*/
+function resolveQueryDriver(requested, isWorker, urls) {
+	if (requested !== void 0 && requested !== "auto") return requested;
+	if (urls?.loki && urls?.opensearch) throw new Error("log.queryDriver ambigu : NF_LOKI_URL ET NF_OPENSEARCH_URL déclarées — préciser log.queryDriver (\"loki\" | \"opensearch\")");
+	if (urls?.loki) return "loki";
+	if (urls?.opensearch) return "opensearch";
+	return isWorker ? "cluster-file" : "memory";
+}
+let registered = false;
+/**
+* Enregistre les fabriques des drivers NATIFS du Log Backplane dans le
+* {@link registerLogDriverFactory registre de fabriques}. Idempotent (appelé à chaque
+* `initializeLog`, court-circuité après la 1ʳᵉ fois). C'est ICI — pas dans le Kernel —
+* que vit la connaissance « nom → comment construire ce driver ». Le Kernel ne fait que
+* résoudre + brancher, sans aucun `if (name === …)`.
+*
+* - `memory` : relit le ring buffer (aucun transport — alimenté par `Syslog`).
+* - `file` / `cluster-file` : relisent un/des JSONL ; écrivent via un `FileTransport`
+*   partagé (même `writeKey` = chemin → branché 1× même si les deux sont montés).
+* - `loki` / `opensearch` : push HTTP batché (transport) + relecture via leur API
+*   (driver) ; `null` si l'URL n'est pas configurée (→ fallback `memory` côté Kernel).
+*/
+function registerBuiltinLogDrivers() {
+	if (registered) return;
+	registered = true;
+	registerLogDriverFactory("memory", (ctx) => ({ driver: createMemoryLogDriver(ctx.getRingStack) }));
+	registerLogDriverFactory("file", (ctx) => {
+		const p = jsonlPath(ctx);
+		const opts = { path: p };
+		const scan = ctx.logCfg?.queryFile?.maxScanBytes;
+		if (scan !== void 0) opts.maxScanBytes = scan;
+		return {
+			driver: createFileLogDriver(opts),
+			transport: new FileTransport({
+				path: p,
+				format: "json"
+			}),
+			writeKey: p
+		};
+	});
+	registerLogDriverFactory("cluster-file", (ctx) => {
+		const p = jsonlPath(ctx);
+		const opts = { dir: path.dirname(p) };
+		const scan = ctx.logCfg?.queryFile?.maxScanBytes;
+		if (scan !== void 0) opts.maxScanBytes = scan;
+		return {
+			driver: createClusterFileLogDriver(opts),
+			transport: new FileTransport({
+				path: p,
+				format: "json"
+			}),
+			writeKey: p
+		};
+	});
+	registerLogDriverFactory("loki", (ctx) => {
+		const lk = ctx.logCfg?.loki;
+		if (!lk?.url) return null;
+		return {
+			driver: createLokiLogDriver(lk),
+			transport: new LokiTransport(lk),
+			writeKey: `loki:${lk.url}`
+		};
+	});
+	registerLogDriverFactory("opensearch", (ctx) => {
+		const os = ctx.logCfg?.opensearch;
+		if (!os?.url) return null;
+		return {
+			driver: createOpenSearchLogDriver(os),
+			transport: new OpenSearchTransport(os),
+			writeKey: `opensearch:${os.url}`
+		};
+	});
+}
+//#endregion
+export { registerBuiltinLogDrivers, resolveQueryDriver };

package/dist/node/syslog/drivers/filterPdus.js

@@ -0,0 +1,71 @@
+import { pduToRecord } from "./ILogDriver.js";
+import { pduProtocol } from "./pduProtocol.js";
+import { pduFlowStep } from "./pduFlow.js";
+//#region src/syslog/drivers/filterPdus.ts
+/** Plafond dur d'enregistrements renvoyés (anti-DoS mémoire/réseau). */
+const MAX_LIMIT = 1e3;
+/** Limite par défaut quand `criteria.limit` est absent. */
+const DEFAULT_LIMIT = 200;
+/** Extrait le texte indexable d'un payload Pdu (string directe, sinon `msg`). */
+const payloadText = (pdu) => {
+	if (typeof pdu.payload === "string") return pdu.payload;
+	if (typeof pdu.payload === "number" || typeof pdu.payload === "boolean") return String(pdu.payload);
+	return "";
+};
+/**
+* Filtre PUR d'un tableau de Pdu selon des critères — **0 I/O, 0 état, testable
+* sans serveur**. C'est LA logique de filtrage du Log Backplane, réutilisée par le
+* driver `memory` (sur `syslog.ringStack`), le futur driver `file` (sur les lignes
+* relues) et la future commande CLI `syslog:filter`. Une logique, trois façades.
+*
+* Critères combinés en **AND** (cf {@link ILogQueryCriteria}). Résultat trié du
+* plus **RÉCENT** au plus ancien (l'entrée naturelle d'un viewer de logs), puis
+* `offset`/`limit` appliqués. `total` = nombre de matchs AVANT pagination.
+*
+* Perf : scan linéaire O(N) sur un ring borné (≤ `maxStack`, ~100-1000). Chemin
+* FROID (admin/debug) → jamais dans le pipeline requête. La sérialisation
+* (Pdu→{@link ILogRecord}) n'est faite que sur la **fenêtre renvoyée**, pas sur
+* tous les matchs.
+*
+* @param pdus - snapshot de Pdu (ex. `syslog.ringStack`, ordre FIFO oldest→newest).
+* @param criteria - critères de filtrage (tous optionnels).
+* @returns enregistrements récents d'abord + total + flag de troncature.
+*/
+function filterPdus(pdus, criteria = {}) {
+	const { requestId, module, msgid, from, to, text, protocol } = criteria;
+	const severities = criteria.severity === void 0 ? null : (Array.isArray(criteria.severity) ? criteria.severity : [criteria.severity]).map((s) => s.toUpperCase());
+	const moduleLc = module ? module.toLowerCase() : null;
+	const msgidLc = msgid ? msgid.toLowerCase() : null;
+	const textLc = text ? text.toLowerCase() : null;
+	const flowSet = criteria.flow === void 0 ? null : new Set(Array.isArray(criteria.flow) ? criteria.flow : [criteria.flow]);
+	const matched = [];
+	for (let i = pdus.length - 1; i >= 0; i--) {
+		const pdu = pdus[i];
+		if (requestId !== void 0 && pdu.requestId !== requestId) continue;
+		if (protocol && pduProtocol(pdu) !== protocol) continue;
+		if (severities && !severities.includes(pdu.severityName.toUpperCase())) continue;
+		if (moduleLc && !pdu.moduleName.toLowerCase().includes(moduleLc)) continue;
+		if (msgidLc && !String(pdu.msgid).toLowerCase().includes(msgidLc)) continue;
+		if (from !== void 0 && pdu.timeStamp < from) continue;
+		if (to !== void 0 && pdu.timeStamp > to) continue;
+		if (flowSet) {
+			const step = pduFlowStep(pdu);
+			if (step === null || !flowSet.has(step)) continue;
+		}
+		if (textLc) {
+			if (!(payloadText(pdu) + " " + pdu.msg + " " + pdu.moduleName + " " + pdu.msgid).toLowerCase().includes(textLc)) continue;
+		}
+		matched.push(pdu);
+	}
+	if (criteria.order === "asc") matched.reverse();
+	const total = matched.length;
+	const offset = criteria.offset && criteria.offset > 0 ? criteria.offset : 0;
+	const limit = Math.min(criteria.limit && criteria.limit > 0 ? criteria.limit : DEFAULT_LIMIT, MAX_LIMIT);
+	return {
+		rows: matched.slice(offset, offset + limit).map(pduToRecord),
+		total,
+		truncated: offset + limit < total
+	};
+}
+//#endregion
+export { filterPdus };

package/dist/node/syslog/drivers/logDriverRegistry.js

@@ -0,0 +1,83 @@
+//#region src/syslog/drivers/logDriverRegistry.ts
+/**
+* Registre des **drivers du Log Backplane** (axe DESTINATION queryable) — résout
+* un nom (`config.log.queryDriver`, env, ou action de contrôle dev-only) vers un
+* `ILogDriver`, SANS aucun `if (name === "elastic") …` en dur.
+*
+* Même philosophie que `backplaneRegistry` (realtime) et `ormRegistry` : les
+* drivers natifs s'enregistrent au boot (`memory` par `Kernel.initializeLog`), un
+* utilisateur peut enregistrer le sien (`registerLogDriver("nats-logs", …)`) puis
+* pointer dessus — aucun changement dans le cœur. Source unique de la résolution.
+*
+* Le **driver actif** détermine où l'on RELIT les logs (`query`). Le sink WRITE
+* texte (LB.W, `Syslog.setLogSink`) et le bus temps réel (`nodefony:syslog`) sont
+* des axes orthogonaux, pilotés séparément.
+*
+* Sélection à la volée : **dev-only** (action de contrôle Studio). En prod, le
+* driver est figé par config/env (12-factor : le routage des logs relève de
+* l'orchestrateur, pas de l'app — un pod qui change de destination en vol = audit
+* cassé / désync cluster).
+*/
+const drivers = /* @__PURE__ */ new Map();
+let active = null;
+/**
+* Enregistre (ou remplace) un driver par son nom. Si aucun driver actif n'est
+* encore défini, le premier enregistré devient actif (défaut sain).
+*
+* @param driver - instance `ILogDriver` (porte son propre `name`).
+*/
+function registerLogDriver(driver) {
+	drivers.set(driver.name, driver);
+	if (active === null) active = driver;
+}
+/**
+* Sélectionne le driver actif par nom (relecture des logs).
+*
+* @param name - nom d'un driver enregistré.
+* @returns le driver activé.
+* @throws si le nom est inconnu (jamais activer un driver fantôme silencieusement).
+*/
+function setActiveLogDriver(name) {
+	const driver = drivers.get(name);
+	if (!driver) throw new Error(`Unknown log driver "${name}". Registered: ${[...drivers.keys()].join(", ") || "(none)"}.`);
+	active = driver;
+	return driver;
+}
+/** Driver actif (relecture), ou `null` si aucun n'est encore enregistré/câblé. */
+function getActiveLogDriver() {
+	return active;
+}
+/**
+* Récupère un driver ENREGISTRÉ par son nom SANS l'activer — pour le sonder
+* (`probe`) ou l'introspecter avant un switch. `undefined` si non enregistré.
+*/
+function getLogDriver(name) {
+	return drivers.get(name);
+}
+/** Liste des drivers enregistrés (introspection Studio / tests / data-plane). */
+function listLogDrivers() {
+	return [...drivers.values()].map((d) => ({
+		name: d.name,
+		capabilities: d.capabilities
+	}));
+}
+const factories = /* @__PURE__ */ new Map();
+/**
+* Enregistre (ou remplace) la fabrique d'un driver par son nom.
+*
+* @param name - nom du driver (`"loki"`, `"opensearch"`, ou custom userland).
+* @param factory - construit le driver + son transport à partir du contexte.
+*/
+function registerLogDriverFactory(name, factory) {
+	factories.set(name, factory);
+}
+/** Récupère la fabrique d'un driver, ou `undefined` si non enregistrée. */
+function getLogDriverFactory(name) {
+	return factories.get(name);
+}
+/** Liste les noms de drivers ayant une fabrique (introspection Studio / CLI). */
+function listLogDriverFactories() {
+	return [...factories.keys()];
+}
+//#endregion
+export { getActiveLogDriver, getLogDriver, getLogDriverFactory, listLogDriverFactories, listLogDrivers, registerLogDriver, registerLogDriverFactory, setActiveLogDriver };

package/dist/node/syslog/drivers/opensearchShared.js

@@ -0,0 +1,17 @@
+//#region src/syslog/drivers/opensearchShared.ts
+/** Index OpenSearch par défaut des logs Nodefony (write transport ↔ read driver). */
+const DEFAULT_OPENSEARCH_INDEX = "nodefony-logs";
+/**
+* Construit l'en-tête `Authorization: Basic …` si un utilisateur est fourni — sinon
+* objet vide (dev = plugin sécurité désactivé, HTTP sans auth). Node-only (`Buffer`).
+*
+* @param username - utilisateur (absent → pas d'auth).
+* @param password - mot de passe.
+* @returns en-tête prêt à étaler, ou `{}`.
+*/
+function basicAuthHeader(username, password) {
+	if (!username) return {};
+	return { authorization: `Basic ${Buffer.from(`${username}:${password ?? ""}`).toString("base64")}` };
+}
+//#endregion
+export { DEFAULT_OPENSEARCH_INDEX, basicAuthHeader };

package/dist/node/syslog/drivers/pduFlow.js

@@ -0,0 +1,106 @@
+//#region src/syslog/drivers/pduFlow.ts
+/**
+* Table des étapes — **source unique** de l'ordre et de l'appartenance protocole,
+* partagée back (filtre) et front (sélecteur groupé HTTP / WebSocket / Commun).
+*/
+const FLOW_STEPS = {
+	"request-in": {
+		order: 1,
+		protocol: "http"
+	},
+	"body-received": {
+		order: 2,
+		protocol: "http"
+	},
+	"route-matched": {
+		order: 3,
+		protocol: "http"
+	},
+	"kernel-dispatch": {
+		order: 4,
+		protocol: "http"
+	},
+	session: {
+		order: 5,
+		protocol: "both"
+	},
+	response: {
+		order: 6,
+		protocol: "http"
+	},
+	"session-saved": {
+		order: 7,
+		protocol: "both"
+	},
+	"request-end": {
+		order: 8,
+		protocol: "http"
+	},
+	finish: {
+		order: 9,
+		protocol: "http"
+	},
+	"ws-open": {
+		order: 1,
+		protocol: "ws"
+	},
+	"ws-message": {
+		order: 2,
+		protocol: "ws"
+	},
+	"ws-close": {
+		order: 3,
+		protocol: "ws"
+	}
+};
+/** Retire les codes de couleur ANSI (les payloads en TTY peuvent en porter). */
+function stripAnsi(s) {
+	return s.replace(/\x1b\[[0-9;]*m/g, "");
+}
+/** Texte indexable d'un Pdu pour la classification (payload string sinon `msg`). */
+function flowText(pdu) {
+	return stripAnsi(typeof pdu.payload === "string" ? pdu.payload : pdu.msg || "");
+}
+/**
+* Classe un Pdu en **étape de cycle de vie** (id stable) ou `null` si la ligne
+* n'est pas un jalon (log applicatif libre, ex. `DB-DEMO`). PUR, isomorphe,
+* 0 état — réutilisé par le filtre back ({@link filterPdus}) ET le rendu front
+* (colonne « Étape » + sélecteur) → une SEULE logique, jamais de divergence.
+*
+* Priorité aux marqueurs de **contenu** (route, session, cookie, bilan), puis au
+* **nom d'event** générique. `onRequest` est désambiguïsé par le msgid `KERNEL`
+* (dispatch kernel) vs contexte (entrée de requête).
+*
+* @param pdu - enregistrement (Pdu ou {@link IPduLike}, relu d'un JSONL aussi).
+* @returns l'`id` d'étape, ou `null` pour un log hors cycle.
+*/
+function pduFlowStep(pdu) {
+	const msg = flowText(pdu);
+	if (/Match route/i.test(msg)) return "route-matched";
+	if (/NEW SESSION|MIGRATE SESSION|DESTROY SESSION|SESSION CONTEXT CHANGE/i.test(msg)) return "session";
+	if (/SAVE SESSION/i.test(msg)) return "session-saved";
+	if (/ADD COOKIE/i.test(msg)) return "response";
+	if (/\bsubscribe\b/i.test(msg)) return "ws-message";
+	if (/client connected/i.test(msg)) return "ws-open";
+	if (/^WS (RECEIVE|SEND|BROADCAST)\b/.test(pdu.msgid)) return "ws-message";
+	if (pdu.msgid === "req") return "request-end";
+	const m = msg.match(/\bon([A-Z][A-Za-z]+)\b/);
+	if (m) {
+		const ev = `on${m[1]}`;
+		if (ev === "onRequest" && pdu.msgid === "KERNEL") return "kernel-dispatch";
+		switch (ev) {
+			case "onRequestEnd": return "body-received";
+			case "onRequest": return "request-in";
+			case "onSessionStart": return "session";
+			case "onConnect": return "ws-open";
+			case "onSaveSession": return "session-saved";
+			case "onSend": return "response";
+			case "onClose": return "ws-close";
+			case "onFinish": return "finish";
+			case "onMessage": return "ws-message";
+		}
+	}
+	return null;
+}
+//#endregion
+export { FLOW_STEPS, pduFlowStep };

package/dist/node/syslog/drivers/pduProtocol.js

@@ -0,0 +1,28 @@
+//#region src/syslog/drivers/pduProtocol.ts
+/**
+* msgid forcé par défaut sur **tout** log émis dans un contexte WebSocket
+* (`WebsocketContext.log()` côté `@nodefony/http`). C'est le marqueur fiable du
+* protocole — pas de parsing de message.
+*/
+const WS_MSGID = "WEBSOCKET CONTEXT";
+/**
+* Classe un Pdu par **protocole** d'origine — `"ws"` ou `"http"` — de façon PURE,
+* isomorphe et 0-alloc (une seule comparaison de `msgid`).
+*
+* Critère FIABLE : tout log émis dans un contexte WebSocket porte le msgid
+* `"WEBSOCKET CONTEXT"` (forcé par défaut dans `WebsocketContext.log()`). Tout le
+* reste du pipeline (req/http2/router/firewall/kernel/applicatif) est classé HTTP.
+* Une seule logique → front et back ne divergent plus (le front filtrait par texte,
+* source de faux positifs).
+*
+* Seul `msgid` compte → accepte un `Pdu`, un {@link IPduLike} ou un record wire
+* relu (`ILogRecord` / miroir front) indifféremment.
+*
+* @param pdu - tout objet portant un `msgid`.
+* @returns `"ws"` si le log provient d'une socket WebSocket, sinon `"http"`.
+*/
+function pduProtocol(pdu) {
+	return pdu.msgid === WS_MSGID ? "ws" : "http";
+}
+//#endregion
+export { pduProtocol };

package/dist/node/syslog/httpFetch.js

@@ -0,0 +1,43 @@
+//#region src/syslog/httpFetch.ts
+/**
+* Résout l'implémentation `fetch` à utiliser : celle passée explicitement (tests,
+* proxy custom), sinon le `fetch` global (Node ≥ 18). Lève si aucune n'est dispo
+* (jamais d'échec silencieux d'un driver prod mal configuré).
+*
+* @param custom - implémentation explicite (prioritaire).
+* @returns un `FetchLike` garanti non nul.
+* @throws si aucun `fetch` n'est disponible.
+*/
+function resolveFetch(custom) {
+	if (custom) return custom;
+	const f = globalThis.fetch;
+	if (typeof f !== "function") throw new Error("global fetch unavailable (Node >= 18 required) — pass fetchImpl explicitly");
+	return f;
+}
+/**
+* `fetch` borné par un timeout (via `AbortController`) — un push/lecture de logs ne
+* doit JAMAIS bloquer indéfiniment sur une destination injoignable. `timeoutMs ≤ 0`
+* = pas de timeout.
+*
+* @param fetchImpl - implémentation `FetchLike`.
+* @param url - URL cible.
+* @param init - options de requête.
+* @param timeoutMs - délai max avant `abort`.
+* @returns la réponse, ou rejette (timeout/réseau).
+*/
+async function fetchWithTimeout(fetchImpl, url, init, timeoutMs) {
+	if (!timeoutMs || timeoutMs <= 0) return fetchImpl(url, init);
+	const ac = new AbortController();
+	const timer = setTimeout(() => ac.abort(), timeoutMs);
+	if (typeof timer.unref === "function") timer.unref();
+	try {
+		return await fetchImpl(url, {
+			...init,
+			signal: ac.signal
+		});
+	} finally {
+		clearTimeout(timer);
+	}
+}
+//#endregion
+export { fetchWithTimeout, resolveFetch };

package/dist/node/syslog/logColor.js

@@ -0,0 +1,80 @@
+import clc from "../colors.js";
+//#region src/syslog/logColor.ts
+/** Combinaisons `cli-color` réellement utilisées par les loggers Nodefony. */
+const KEYS = [
+	"cyan",
+	"magenta",
+	"red",
+	"green",
+	"yellow",
+	"blue",
+	"blackBright",
+	"yellowBold",
+	"redBold",
+	"cyanBold",
+	"blueBrightBold",
+	"cyanBgBlue",
+	"cyanBgBlack"
+];
+const identity = (s) => s;
+/** Implémentation colorée (TTY) — résolue 1× à l'import (chaînage figé). */
+const COLORS = {
+	cyan: clc.cyan,
+	magenta: clc.magenta,
+	red: clc.red,
+	green: clc.green,
+	yellow: clc.yellow,
+	blue: clc.blue,
+	blackBright: clc.blackBright,
+	yellowBold: clc.yellow.bold,
+	redBold: clc.red.bold,
+	cyanBold: clc.cyan.bold,
+	blueBrightBold: clc.blueBright.bold,
+	cyanBgBlue: clc.cyan.bgBlue,
+	cyanBgBlack: clc.cyan.bgBlack
+};
+/**
+* Helper de couleur partagé — référence STABLE, propriétés mutées par
+* {@link setLogColor}. Les call-sites font `logColor.cyan("URL")`.
+*/
+const logColor = { ...COLORS };
+let _enabled = false;
+/**
+* Active/désactive la couleur ANSI des logs — à appeler **une fois au boot**.
+* Swap les fonctions des slots ; aucun coût par log ensuite.
+*
+* @param enabled - `true` = couleur (TTY interactif), `false` = brut (pipe/fichier).
+*/
+function setLogColor(enabled) {
+	_enabled = enabled;
+	for (const k of KEYS) logColor[k] = enabled ? COLORS[k] : identity;
+}
+/** `true` si la couleur ANSI est active (gate boot-time). */
+function isLogColorEnabled() {
+	return _enabled;
+}
+/**
+* Applique les conventions d'environnement couleur PAR-DESSUS un signal `isTTY`
+* **déjà résolu** — au boot on passe `Kernel.isTTY` (qui honore déjà `NF_NO_TTY`),
+* sans re-lire `process.stdout`. Conventions :
+*
+* - **`NO_COLOR`** (no-color.org) : présent **et non vide** → couleur OFF, quelle
+*   que soit sa valeur. Priorité absolue (refus explicite de l'utilisateur).
+* - **`FORCE_COLOR`** : non vide et ≠ `"0"` → couleur ON (override pipe/non-TTY,
+*   ex. CI qui veut des logs colorés capturés).
+* - sinon → couleur = `isTTY`.
+*
+* Isomorphe : `env` lu via `globalThis.process` (navigateur : pas de `process`).
+*
+* @param isTTY - signal TTY déjà résolu (ex. `Kernel.isTTY`, NF_NO_TTY-aware).
+*/
+function resolveColorEnabled(isTTY) {
+	const env = globalThis.process?.env ?? {};
+	if (typeof env.NO_COLOR === "string" && env.NO_COLOR !== "") return false;
+	if (typeof env.FORCE_COLOR === "string" && env.FORCE_COLOR !== "" && env.FORCE_COLOR !== "0") return true;
+	return isTTY;
+}
+const _importProc = globalThis.process;
+setLogColor(resolveColorEnabled(_importProc?.env?.NF_NO_TTY ? false : _importProc?.stdout?.isTTY === true));
+//#endregion
+export { isLogColorEnabled, logColor, resolveColorEnabled, setLogColor };