@nodefony/framework 10.0.0-alpha.1

package/dist/nodefony/src/KernelAdminApi.js

@@ -0,0 +1,1243 @@
+import { CORE_PACKAGE, checkOutdated, countModuleDocs, listModuleDocs, listModuleSymbols, listTestFiles, listTestGroups, readCoreInfo, readCoverage, readDependencies, readModuleDoc, readSymbolDeclaration, resolveCorePath, runModuleTests, searchModuleDocs } from "./docsReader.js";
+import { getResolvedPath, navigateSchemaNode, nodeFlags, notEditableReason, recipeFor, validateLeafValue } from "./configMutation.js";
+import { createRequire } from "node:module";
+import { join } from "node:path";
+import { GitService, Syslog, applyResolvedPath, collectDevStatus, computeConfigProvenance, defaultAppConfig, extractJsonSchemaDefaults, extractMarkdownSection, getActiveLogDriver, listLogDrivers, outlineMarkdown, parseNfEnvOverrides } from "nodefony";
+import { randomUUID } from "node:crypto";
+import { existsSync, readFileSync } from "node:fs";
+//#region nodefony/src/KernelAdminApi.ts
+/** Clé du pseudo-module core dans Studio (cf carte "Core" / `resolveCorePath`). */
+const CORE_KEY = "core";
+/** Racine projet — pour ne PAS exposer de chemin absolu (sécu). */
+const REPO_ROOT = process.cwd();
+/** Relativise tout chemin absolu présent dans une string de config. */
+function stripAbs(s) {
+	if (!s.includes(REPO_ROOT)) return s;
+	return s.split(`${REPO_ROOT}/`).join("").split(REPO_ROOT).join(".");
+}
+/**
+* Adapters de persistance OFFICIELS — juste les NOMS, pour la découvrabilité (savoir
+* qu'ils existent même NON installés → état « à installer »). Leurs CAPABILITÉS
+* (domaine + briques couvertes) ne sont PAS curatées ici : chaque adapter les DÉCLARE
+* dans son `package.json` (`nodefony.storeKind` + `nodefony.stores`), lues à chaud par
+* {@link readAdapterManifest} (Palier 3 — source de vérité = l'adapter, extensible aux
+* modules tiers, jamais figée dans le core).
+*/
+const OFFICIAL_STORE_ADAPTERS = [
+	{
+		engine: "drizzle",
+		package: "@nodefony/drizzle",
+		family: "sql"
+	},
+	{
+		engine: "mongoose",
+		package: "@nodefony/mongoose",
+		family: "mongo"
+	},
+	{
+		engine: "redis",
+		package: "@nodefony/redis",
+		family: "cache"
+	}
+];
+/**
+* Lit les capabilités DÉCLARÉES d'un adapter installé depuis son `package.json`
+* (`nodefony.storeKind` = `durable|cache` ; `nodefony.stores` = briques couvertes).
+* `null` si non installé ou sans déclaration. Le modèle est « couverture ADAPTÉE à la
+* vocation », pas une parité 8/8 : un adapter déclare ce qu'il implémente, point.
+*/
+function readAdapterManifest(pkg) {
+	const pkgJson = join(REPO_ROOT, "node_modules", ...pkg.split("/"), "package.json");
+	try {
+		if (!existsSync(pkgJson)) return null;
+		const nf = JSON.parse(readFileSync(pkgJson, "utf8")).nodefony;
+		if (!nf || !Array.isArray(nf.stores)) return null;
+		return {
+			storeKind: nf.storeKind === "cache" ? "cache" : "durable",
+			stores: nf.stores.filter((s) => typeof s === "string")
+		};
+	} catch {
+		return null;
+	}
+}
+const engineRequire = createRequire(import.meta.url);
+/**
+* Un package npm est-il INSTALLÉ (résolvable), qu'il soit chargé ou non ? Distingue
+* « installé mais pas branché au manifeste » de « à installer ». Résolution standard
+* d'abord ; repli sur la présence du dossier dans `node_modules` du projet (hoisting
+* monorepo — `exports` peut ne pas publier tous les sous-chemins).
+*/
+function isPackageInstalled(pkg) {
+	try {
+		engineRequire.resolve(pkg);
+		return true;
+	} catch {
+		return existsSync(join(REPO_ROOT, "node_modules", ...pkg.split("/")));
+	}
+}
+/**
+* Clés dont la VALEUR est un secret (JWT, CSRF, OAuth client secret, clé de
+* chiffrement). Redactées dans la config exposée au data plane — Zero Trust :
+* un secret n'est JAMAIS renvoyé en clair, même à un admin.
+*
+* ## Pourquoi un motif de MOT ENTIER, et pas une sous-chaîne
+*
+* La forme précédente cherchait ces mots n'importe où dans la clé. Elle laissait
+* passer **`encryptionKey`** — mesuré : `security.totp.encryptionKey` et
+* `security.webhooks.encryptionKey` sortaient en clair —, et rédigeait à tort
+* `privateKeyMode`, qui n'est qu'un MODE (`"file"`, `"env"`).
+*
+* L'élargir à `key` tout court n'était pas la réponse : sur une application
+* réelle, cela emportait `apiKeys.prefix`, `passkeys.timeoutMs`,
+* `tokenStore.gcIntervalS` et jusqu'à `key: "app"`, l'identifiant de module dont
+* la console d'administration se sert pour indexer ses entrées. Une règle qui
+* rédige du non-secret n'est pas « prudente » : elle rend l'écran inutilisable,
+* donc on finit par la retirer.
+*
+* ⚠️ Cette liste doit rester alignée avec `pathLooksSecret`
+* (`config/envOverride.ts`), qui rend le même jugement pour les journaux. Elles
+* ont divergé — c'est cette divergence qui a laissé fuir `encryptionKey`.
+*/
+const SECRET_KEY = /(?:^|[a-z0-9])(secret|password|passwd|passphrase|credential|clientsecret|keysetjson|privatekey|encryptionkey|signingkey|accesstoken|refreshtoken)s?$/i;
+/**
+* Sérialisation défensive de config : borne la profondeur, neutralise les
+* fonctions, casse les cycles, et **relativise les chemins absolus** (sécu :
+* ne jamais exposer l'arborescence serveur). Les `options` d'un module peuvent
+* contenir des fonctions/refs circulaires (vers le kernel) → JSON.stringify
+* direct planterait.
+*/
+function safeConfig(value, depth = 0, seen = /* @__PURE__ */ new WeakSet()) {
+	if (typeof value === "function") return "[Function]";
+	if (typeof value === "bigint") return value.toString();
+	if (typeof value === "string") return stripAbs(value);
+	if (value === null || typeof value !== "object") return value;
+	if (depth > 5) return "[depth limit]";
+	if (seen.has(value)) return "[Circular]";
+	seen.add(value);
+	if (value instanceof Date) return value.toISOString();
+	if (value instanceof RegExp) return value.toString();
+	if (Array.isArray(value)) return value.slice(0, 100).map((v) => safeConfig(v, depth + 1, seen));
+	const out = {};
+	for (const k of Object.keys(value).slice(0, 200)) {
+		const raw = value[k];
+		if (SECRET_KEY.test(k) && raw != null && raw !== "" && typeof raw !== "boolean" && typeof raw !== "object") {
+			out[k] = "[redacted]";
+			continue;
+		}
+		try {
+			out[k] = safeConfig(raw, depth + 1, seen);
+		} catch {
+			out[k] = "[unreadable]";
+		}
+	}
+	return out;
+}
+/**
+* Aplatit un objet de config en chemins-feuilles pointés MINUSCULES (les arrays
+* sont des feuilles). Sert à savoir quels chemins un override `module-<X>` déclare.
+*/
+function flattenPaths(value, prefix, out) {
+	if (value !== null && typeof value === "object" && !Array.isArray(value)) for (const k of Object.keys(value)) flattenPaths(value[k], prefix ? `${prefix}.${k}` : k, out);
+	else if (prefix) out.add(prefix.toLowerCase());
+}
+/**
+* Attribue chaque champ **app**-surchargé à sa SOURCE réelle (mute `overriddenBy`).
+*
+* Construit l'index inversé des overrides `module-<cible>` déclarés par CHAQUE
+* module (y compris l'app), puis, pour chaque champ « app » d'une cible, retrouve
+* le module qui pose ce chemin → c'est le vrai « qui surcharge ». Aucun candidat
+* `module-<cible>` → la surcharge vient de la config app directe (`nodefony.config.ts`).
+*
+* @param entries - toutes les entrées config de l'agrégat (mutées en place).
+*/
+function attributeOverrideSources(entries) {
+	const byTarget = /* @__PURE__ */ new Map();
+	for (const e of entries) for (const key of Object.keys(e.config)) {
+		const m = /^module-(.+)$/i.exec(key);
+		if (!m) continue;
+		const targetSeg = m[1].toLowerCase();
+		const paths = /* @__PURE__ */ new Set();
+		flattenPaths(e.config[key], "", paths);
+		const arr = byTarget.get(targetSeg);
+		if (arr) arr.push({
+			source: e.name,
+			paths
+		});
+		else byTarget.set(targetSeg, [{
+			source: e.name,
+			paths
+		}]);
+	}
+	for (const e of entries) {
+		if (!e.provenance) continue;
+		const candidates = byTarget.get(e.seg);
+		for (const [path, origin] of Object.entries(e.provenance)) {
+			if (origin !== "app") continue;
+			const pl = path.toLowerCase();
+			const hit = candidates?.find((c) => c.paths.has(pl) || [...c.paths].some((p) => pl.startsWith(`${p}.`) || p.startsWith(`${pl}.`)));
+			e.overriddenBy[path] = hit ? hit.source : "nodefony.config.ts";
+		}
+	}
+}
+/** Segment d'adressage des overrides (`NF__<SEG>__…`) d'un module : `app` ou le basename. */
+function computeSeg(pkg, isApp) {
+	if (isApp) return "app";
+	return (pkg.includes("/") ? pkg.slice(pkg.lastIndexOf("/") + 1) : pkg).toLowerCase();
+}
+/**
+* Calcule l'entrée CONFIG d'un module — partagée par `module/{name}` (détail) et
+* l'agrégat `config` (page globale). Une seule logique de provenance (ADR-0006 D7),
+* branche `isApp` (défauts = `defaultAppConfig`, env = segment réservé `app`) vs
+* module (défauts = `extractJsonSchemaDefaults(schema)`, env = basename). La map de
+* provenance ne porte que des ORIGINES (jamais de valeur → 0 fuite) ; les valeurs
+* restent redactées par `safeConfig`.
+*
+* @param key - clé Studio du module.
+* @param mod - module (forme minimale {@link ConfigModuleLike}).
+* @param runtimePaths - chemins (pointés minuscule) édités À CHAUD via PATCH →
+*   provenance forcée `runtime` (≠ `app` : la valeur ne vient pas de la config app).
+* @returns l'entrée config normalisée.
+*/
+function computeConfigEntry(key, mod, runtimePaths) {
+	const pkg = mod.getModuleName?.() ?? key;
+	const opts = mod.options ?? {};
+	const schema = mod.configSchema();
+	const isApp = mod.isApp ?? false;
+	const seg = computeSeg(pkg, isApp);
+	const envKeys = {};
+	for (const o of parseNfEnvOverrides(process.env)) if (o.moduleSeg === seg) envKeys[o.path.join(".")] = o.envKey;
+	let provenance = null;
+	if (isApp) {
+		const envPaths = new Set(parseNfEnvOverrides(process.env).filter((o) => o.moduleSeg === "app").map((o) => o.path.join(".")));
+		provenance = computeConfigProvenance(opts, defaultAppConfig, envPaths);
+	} else if (schema) {
+		const envPaths = new Set(parseNfEnvOverrides(process.env).filter((o) => o.moduleSeg === seg).map((o) => o.path.join(".")));
+		provenance = computeConfigProvenance(opts, extractJsonSchemaDefaults(schema), envPaths);
+	}
+	if (provenance && runtimePaths && runtimePaths.size) {
+		for (const k of Object.keys(provenance)) if (runtimePaths.has(k.toLowerCase())) provenance[k] = "runtime";
+	}
+	return {
+		key,
+		name: pkg,
+		isApp,
+		seg,
+		config: safeConfig(opts),
+		configSchema: schema,
+		provenance,
+		envKeys,
+		overriddenBy: {}
+	};
+}
+/** Libellé d'identité de l'acteur d'une mutation (duck-type `IUser`, sans import). */
+function actorLabel(user) {
+	if (!user || typeof user !== "object") return null;
+	const u = user;
+	if (typeof u.getUserIdentifier === "function") try {
+		return u.getUserIdentifier();
+	} catch {}
+	return u.username ?? u.email ?? (u.id != null ? String(u.id) : null);
+}
+/**
+* Journalise une mutation de config (catégorie `config`) **si** le service d'audit
+* est présent — résolution par nom dans le container du kernel, no-op sinon (même
+* découplage que `recordAudit` côté security : framework n'importe pas security).
+* Un secret n'arrive jamais ici (refusé en amont par {@link notEditableReason}).
+*/
+function auditConfigChange(kernel, request, moduleKey, path, before, after) {
+	(kernel.container?.get("auditService"))?.record?.({
+		category: "config",
+		action: "config.update",
+		outcome: "success",
+		actor: actorLabel(request.user),
+		resource: `${moduleKey}.${path}`,
+		requestId: request.requestId ?? null,
+		metadata: {
+			before,
+			after
+		}
+	});
+}
+/**
+* Journalise un changement de debug runtime (catégorie `log`). Même découplage
+* que {@link auditConfigChange} (résolution par nom, no-op si pas d'audit).
+*/
+function auditLogLevelChange(kernel, request, module, action, level, ttlMs) {
+	(kernel.container?.get("auditService"))?.record?.({
+		category: "log",
+		action: `log.debug.${action}`,
+		outcome: "success",
+		actor: actorLabel(request.user),
+		resource: module,
+		requestId: request.requestId ?? null,
+		metadata: {
+			level,
+			ttlMs
+		}
+	});
+}
+/** TTL par défaut d'un debug ciblé ouvert via l'endpoint (15 min). */
+const DEFAULT_DEBUG_TTL_MS = 9e5;
+/** Plafond dur du TTL (60 min) — borne anti-« debug oublié allumé » en prod. */
+const MAX_DEBUG_TTL_MS = 36e5;
+/**
+* Producteur `IAdminApi` du **kernel** — exposé sous `/nodefony/kernel/api/*`.
+*
+* Le kernel ne peut pas s'enregistrer lui-même : il vit dans `@nodefony/core`
+* et ne peut donc pas importer le broker (qui est dans `@nodefony/framework`).
+* C'est framework qui construit cet `IAdminApi` à partir du kernel et
+* l'enregistre auprès du broker (cf `Framework.onKernelReady`). Le kernel reste
+* passif : on ne lit que ses getters publics + `process`.
+*
+* Endpoints (tous `ROLE_NODEFONY_ADMIN` par défaut) :
+*  - `GET /nodefony/kernel/api/health`  → liveness léger (probe k8s-friendly)
+*  - `GET /nodefony/kernel/api/info`    → identité runtime
+*  - `GET /nodefony/kernel/api/modules` → modules chargés + versions
+*
+* @param kernel - kernel courant (`Nodefony.getKernel()`).
+* @returns le contrat admin du kernel, prêt à `broker.register()`.
+*/
+/**
+* Forme admise d'un nom de paquet npm — la garde entre un paramètre de route et
+* une jointure de chemin. Sans elle, « ../../etc » désignerait un dossier hors
+* de l'arbre des dépendances.
+*/
+const PACKAGE_NAME = /^(?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/;
+/**
+* Paquets à essayer pour une clé de module, **dans l'ordre**, et bornés au
+* périmètre du framework.
+*
+* Pure — donc éprouvable sans disque ni dossier courant, et c'est nécessaire :
+* les deux défauts qu'elle corrige tiennent l'un à l'ORDRE, l'autre au
+* PÉRIMÈTRE, jamais au système de fichiers.
+*
+* 🔴 **Le scope d'abord.** `redis` désigne ici le module Nodefony — mais un
+* client Redis tiers du même nom vit dans le même `node_modules`. L'essayer en
+* premier le faisait gagner : le paquet trouvé n'avait pas de documentation,
+* la réponse sortait VIDE, et le cas exact qu'on venait de corriger était le
+* seul à rater. Un nom court est une clé Nodefony avant d'être un nom npm ;
+* l'homonyme tiers ne vient qu'après.
+*
+* 🔴 **Le périmètre n'est pas la traversée.** {@link PACKAGE_NAME} empêche
+* `../../etc` de désigner un dossier hors de l'arbre — elle ne dit rien de ce
+* qu'on a le droit de servir. Sans cette seconde garde, la porte de
+* documentation rendait les pages de n'importe quelle dépendance installée
+* (`chrome-launcher` en a), c'est-à-dire qu'elle exposait l'arbre de
+* dépendances d'une application à qui interroge la porte.
+*
+* ⚠️ `nodefony` en toutes lettres : le socle se nomme ainsi sur npm (héritage
+* du dépôt JS) quand le reste de la pile porte le scope ; `CORE_PACKAGE` est
+* son nom LOGIQUE, pas celui du dossier installé.
+*
+* @param name - clé courte (`redis`) ou nom de paquet (`@nodefony/redis`).
+* @returns les noms de paquets à tenter, du plus probable au moins probable.
+*/
+function nodefonyPackageCandidates(name) {
+	if (!PACKAGE_NAME.test(name)) return [];
+	const inScope = (pkg) => pkg === "nodefony" || pkg === "@nodefony/core" || pkg.startsWith("@nodefony/");
+	return (name.includes("/") ? [name] : [`@nodefony/${name}`, name]).filter(inScope);
+}
+function createKernelAdminApi(kernel) {
+	const descriptor = {
+		label: "Kernel",
+		icon: "server",
+		order: 0
+	};
+	const resolveTarget = (key) => {
+		if (key === CORE_KEY) return {
+			path: resolveCorePath(),
+			pkg: CORE_PACKAGE
+		};
+		const mod = kernel.getModules()[key];
+		if (!mod) return null;
+		return {
+			path: mod.path,
+			pkg: mod.getModuleName?.() ?? key
+		};
+	};
+	const resolvePackageDir = (name) => {
+		for (const candidate of nodefonyPackageCandidates(name)) {
+			const dir = join(repoRoot, "node_modules", candidate);
+			if (existsSync(join(dir, "package.json"))) return dir;
+		}
+		return null;
+	};
+	/**
+	* Chemin d'un porteur de documentation, module CHARGÉ ou paquet INSTALLÉ.
+	*
+	* ⚠️ Les deux cas existent et se confondaient en un seul refus. Un paquet
+	* peut être présent dans l'arbre des dépendances — sa documentation livrée
+	* avec lui — sans que le kernel l'ait chargé : `orm-core` est une
+	* bibliothèque pure, `redis` peut n'être pas activé dans cette application.
+	* Répondre « module introuvable » sur des pages parfaitement présentes
+	* faisait conclure qu'elles n'existaient pas, alors qu'elles sont
+	* précisément ce que git ignore et que les outils de recherche excluent.
+	*
+	* @param key - clé courte (`http`) ou nom de paquet (`@nodefony/redis`).
+	* @returns le dossier à lire, ou `null`.
+	*/
+	const resolveDocDir = (key) => resolveTarget(key)?.path ?? resolvePackageDir(key);
+	/**
+	* Ce qu'on peut proposer à qui s'est trompé de nom — les clés qui répondent.
+	*
+	* Un refus qui ne nomme AUCUNE valeur valide laisse deviner, puis abandonner :
+	* l'appelant conclut que la ressource n'existe pas, quand il a seulement mal
+	* orthographié. Le secours accompagne donc le refus, il ne s'obtient pas par
+	* un second appel que personne ne pense à faire.
+	*/
+	const docKeys = () => [CORE_KEY, ...Object.keys(kernel.getModules())];
+	const docTargets = () => {
+		const targets = [];
+		for (const key of [CORE_KEY, ...Object.keys(kernel.getModules())]) {
+			const target = resolveTarget(key);
+			if (target) targets.push({
+				key,
+				path: target.path
+			});
+		}
+		return targets;
+	};
+	const testJobs = /* @__PURE__ */ new Map();
+	const runtimeEdited = /* @__PURE__ */ new Map();
+	const devGuard = () => kernel.environment === "development" || Boolean(kernel.debug);
+	const repoRoot = process.cwd();
+	const relPath = (p) => p && p.startsWith(repoRoot) ? p.slice(repoRoot.length).replace(/^[/\\]+/, "") || "." : p ?? null;
+	const redactInfraUrl = (url) => url.replace(/\/\/[^/@]*@/, "//***@");
+	const buildConfigEntries = () => {
+		const modules = kernel.getModules();
+		const entries = [];
+		for (const k of Object.keys(modules)) {
+			const mod = modules[k];
+			const opts = mod.options ?? {};
+			if (Object.keys(opts).length === 0 && !mod.configSchema()) continue;
+			entries.push(computeConfigEntry(k, mod, runtimeEdited.get(k)));
+		}
+		attributeOverrideSources(entries);
+		return entries;
+	};
+	const resolveSourceFile = (src) => {
+		if (src === "nodefony.config.ts") return src;
+		for (const [k, m] of Object.entries(kernel.getModules())) {
+			const mm = m;
+			if ((mm.getModuleName?.() ?? k) !== src) continue;
+			if (mm.isApp) return "nodefony.config.ts";
+			if (!mm.path) return src;
+			const cfg = join(mm.path, "nodefony", "config", "config.ts");
+			return existsSync(cfg) ? relPath(cfg) ?? src : relPath(mm.path) ?? src;
+		}
+		return src;
+	};
+	const resolveStoreSource = (configPath, entriesBySeg) => {
+		if (!configPath) return null;
+		const dot = configPath.indexOf(".");
+		if (dot < 0) return null;
+		const seg = configPath.slice(0, dot).toLowerCase();
+		const field = configPath.slice(dot + 1).toLowerCase();
+		const entry = entriesBySeg.get(seg);
+		if (!entry?.provenance) return null;
+		const key = Object.keys(entry.provenance).find((k) => k.toLowerCase() === field);
+		const origin = key ? entry.provenance[key] : void 0;
+		if (!origin || !key) return null;
+		if (origin === "env") return {
+			origin,
+			detail: entry.envKeys[key] ?? "variable d'environnement"
+		};
+		if (origin === "app") return {
+			origin,
+			detail: resolveSourceFile(entry.overriddenBy[key] ?? "nodefony.config.ts")
+		};
+		if (origin === "runtime") return {
+			origin,
+			detail: "édition à chaud (Studio)"
+		};
+		return {
+			origin,
+			detail: "défaut du schéma"
+		};
+	};
+	const endpoints = [
+		{
+			path: "health",
+			summary: "Liveness probe — process up + boot status",
+			handler: () => ({
+				status: kernel.booted ? "ok" : "booting",
+				booted: kernel.booted,
+				uptime: process.uptime(),
+				pid: process.pid
+			})
+		},
+		{
+			path: "livez",
+			public: true,
+			summary: "Liveness/readiness probe (PUBLIC) — détails runtime gradués par authentification",
+			handler: (request) => {
+				const report = kernel.getBootReport();
+				const blocked = kernel.readinessBlocked;
+				const minimal = {
+					status: kernel.booted ? "ok" : "booting",
+					booted: kernel.booted,
+					ready: kernel.servable,
+					/** Nombre de composants qui retiennent la mise en service (0 = aucun). */
+					readinessBlocked: blocked,
+					degraded: report.modulesSkipped.length > 0 || !report.healthy,
+					uptime: process.uptime(),
+					environment: kernel.environment
+				};
+				const httpStatus = kernel.booted ? 200 : 503;
+				if (!request.roles.some((r) => r !== "ROLE_ANONYMOUS")) return {
+					status: httpStatus,
+					body: minimal
+				};
+				return {
+					status: httpStatus,
+					body: {
+						...minimal,
+						version: kernel.version,
+						debug: kernel.debug,
+						pid: process.pid,
+						node: process.version,
+						platform: process.platform,
+						memory: process.memoryUsage(),
+						modules: Object.keys(kernel.getModules()).length,
+						modulesSkipped: report.modulesSkipped,
+						remediation: report.remediation,
+						readiness: kernel.readinessReport(),
+						cluster: { isCluster: process.env.NF_CLUSTER === "1" },
+						backplanes: { log: {
+							driver: getActiveLogDriver()?.name ?? null,
+							sink: Syslog.logSinkName
+						} },
+						git: GitService.read()
+					}
+				};
+			}
+		},
+		{
+			path: "info",
+			summary: "Runtime identity — version, environment, host",
+			handler: () => ({
+				version: kernel.version,
+				environment: kernel.environment,
+				debug: kernel.debug,
+				domain: kernel.domain,
+				pid: process.pid,
+				node: process.version,
+				platform: process.platform,
+				uptime: process.uptime(),
+				modules: Object.keys(kernel.getModules()).length,
+				cluster: { isCluster: process.env.NF_CLUSTER === "1" },
+				backplanes: { log: {
+					driver: getActiveLogDriver()?.name ?? null,
+					sink: Syslog.logSinkName,
+					available: listLogDrivers().map((d) => ({
+						name: d.name,
+						query: d.capabilities.query,
+						stream: d.capabilities.stream
+					}))
+				} },
+				git: GitService.read()
+			})
+		},
+		{
+			path: "processes",
+			summary: "Dev process topology (supervisor → server → Vite) + server ports — `nodefony status` over the data plane",
+			handler: async () => {
+				if (!devGuard()) return {
+					devMode: false,
+					supported: true,
+					running: false,
+					processes: [],
+					ports: [],
+					summary: {
+						supervisors: 0,
+						servers: 0,
+						vites: 0,
+						portsUp: 0,
+						portsTotal: 0
+					},
+					warnings: [],
+					pidfile: {
+						path: "",
+						pid: null,
+						alive: false
+					}
+				};
+				return {
+					devMode: true,
+					...await collectDevStatus(REPO_ROOT, { includeSelf: true })
+				};
+			}
+		},
+		{
+			path: "modules",
+			summary: "Loaded modules with their versions (+ core pseudo-module)",
+			handler: async () => {
+				const modules = kernel.getModules();
+				const core = await readCoreInfo();
+				const list = [{
+					key: CORE_KEY,
+					name: core.name,
+					version: core.version,
+					isApp: false,
+					path: relPath(core.path)
+				}];
+				for (const name of Object.keys(modules)) {
+					const mod = modules[name];
+					list.push({
+						key: name,
+						name: mod.getModuleName?.() ?? name,
+						version: mod.getModuleVersion?.() ?? null,
+						isApp: mod.isApp ?? false,
+						path: relPath(mod.path)
+					});
+				}
+				return list;
+			}
+		},
+		{
+			path: "services",
+			summary: "Every service registered by every module, with its implementing class",
+			handler: () => {
+				const modules = kernel.getModules();
+				const services = [];
+				for (const name of Object.keys(modules)) {
+					const mod = modules[name];
+					for (const service of mod.getServiceNames?.() ?? []) services.push({
+						name: service,
+						module: name,
+						class: mod.get(service)?.constructor?.name ?? null
+					});
+				}
+				services.sort((a, b) => `${a.module}.${a.name}`.localeCompare(`${b.module}.${b.name}`));
+				return services;
+			}
+		},
+		{
+			path: "config",
+			summary: "Aggregated config of all modules (effective values redacted + JSON Schema + per-field provenance) for the global config page",
+			handler: async () => ({ modules: buildConfigEntries() })
+		},
+		{
+			path: "stores",
+			summary: "Runtime persistence stores per brick (resolved store, provenance, available backends) + declared infra",
+			handler: () => {
+				const infra = kernel.infra;
+				const entriesBySeg = new Map(buildConfigEntries().map((e) => [e.seg, e]));
+				const dbUrl = infra.database ? redactInfraUrl(infra.database.url) : null;
+				const cacheUrl = infra.cache ? redactInfraUrl(infra.cache.url) : null;
+				const storeEndpoint = (res) => {
+					if (res.location) return void 0;
+					if (res.resolved === "redis") return cacheUrl ?? void 0;
+					if (res.resolved === "drizzle" || res.resolved === "mongoose") return dbUrl ?? void 0;
+				};
+				const infraVar = (res) => {
+					if (res.resolved === "redis" && infra.cache) return "NF_REDIS_URL";
+					if ((res.resolved === "drizzle" || res.resolved === "mongoose") && infra.database) return "NF_DATABASE_URL";
+					return null;
+				};
+				const registered = new Set(kernel.storeResolutions.flatMap((r) => [...r.available]));
+				return {
+					engines: OFFICIAL_STORE_ADAPTERS.map((a) => {
+						const manifest = readAdapterManifest(a.package);
+						return {
+							engine: a.engine,
+							package: a.package,
+							family: a.family,
+							kind: manifest?.storeKind ?? "durable",
+							provides: manifest?.stores ?? [],
+							installed: manifest !== null || isPackageInstalled(a.package),
+							loaded: registered.has(a.engine)
+						};
+					}),
+					infra: {
+						database: infra.database ? {
+							scheme: infra.database.scheme,
+							family: infra.database.family,
+							dialect: infra.database.dialect,
+							url: dbUrl
+						} : null,
+						cache: infra.cache ? { url: cacheUrl } : null,
+						logs: infra.logs ? {
+							lokiUrl: infra.logs.lokiUrl ? redactInfraUrl(infra.logs.lokiUrl) : null,
+							opensearchUrl: infra.logs.opensearchUrl ? redactInfraUrl(infra.logs.opensearchUrl) : null
+						} : null
+					},
+					stores: kernel.storeResolutions.map((res) => {
+						const iv = res.provenance === "infra" ? infraVar(res) : null;
+						return {
+							...res,
+							endpoint: storeEndpoint(res),
+							source: iv ? {
+								origin: "infra",
+								detail: iv
+							} : resolveStoreSource(res.configPath, entriesBySeg)
+						};
+					})
+				};
+			}
+		},
+		{
+			path: "config/{module}",
+			method: "PATCH",
+			summary: "Live-edit one runtimeMutable config field of a module (dev only) — validated + audited",
+			handler: (request) => {
+				if (!devGuard()) return {
+					status: 409,
+					body: {
+						error: "Config live-edit disabled outside development",
+						reason: "prod_immutable"
+					}
+				};
+				const key = request.params.module;
+				const mod = kernel.getModules()[key];
+				if (!mod) return {
+					status: 404,
+					body: {
+						error: "Module not found",
+						key,
+						available: docKeys()
+					}
+				};
+				const body = request.body ?? {};
+				if (typeof body.path !== "string" || body.path.length === 0) return {
+					status: 400,
+					body: { error: "Missing 'path'" }
+				};
+				const segments = body.path.split(".").filter((s) => s.length > 0);
+				if (segments.length === 0) return {
+					status: 400,
+					body: {
+						error: "Invalid 'path'",
+						path: body.path
+					}
+				};
+				const value = body.value;
+				const schema = mod.configSchema();
+				if (!schema) return {
+					status: 409,
+					body: {
+						error: "Module has no Zod schema — live-edit unavailable",
+						reason: "no_schema"
+					}
+				};
+				const node = navigateSchemaNode(schema, segments);
+				if (!node) return {
+					status: 404,
+					body: {
+						error: "Unknown config path",
+						path: body.path
+					}
+				};
+				const flags = nodeFlags(node);
+				const seg = computeSeg(mod.getModuleName?.() ?? key, mod.isApp ?? false);
+				const reason = notEditableReason(flags);
+				if (reason) return {
+					status: 409,
+					body: {
+						error: "Field is not live-editable",
+						reason,
+						recipe: recipeFor(seg, segments, flags.secret)
+					}
+				};
+				const verdict = validateLeafValue(node, value);
+				if (!verdict.ok) return {
+					status: 422,
+					body: {
+						error: "Invalid value",
+						message: verdict.message
+					}
+				};
+				const opts = mod.options ?? {};
+				const before = getResolvedPath(opts, segments);
+				if (!applyResolvedPath(opts, segments, value)) return {
+					status: 422,
+					body: {
+						error: "Path not present in module config",
+						path: body.path
+					}
+				};
+				const svcMod = mod;
+				for (const sname of svcMod.getServiceNames?.() ?? []) {
+					const svc = svcMod.get?.(sname);
+					if (svc?.options && svc.options !== opts) applyResolvedPath(svc.options, segments, value);
+					svc?.onConfigChanged?.(segments);
+				}
+				let edited = runtimeEdited.get(key);
+				if (!edited) {
+					edited = /* @__PURE__ */ new Set();
+					runtimeEdited.set(key, edited);
+				}
+				edited.add(body.path.toLowerCase());
+				auditConfigChange(kernel, request, key, body.path, before, value);
+				return {
+					status: 200,
+					body: {
+						ok: true,
+						key,
+						path: body.path,
+						value,
+						provenance: "runtime"
+					}
+				};
+			}
+		},
+		{
+			path: "log/level",
+			summary: "Current runtime debug state — global DEBUG flag + active per-module overrides",
+			handler: () => {
+				const syslog = kernel.syslog;
+				if (!syslog) return {
+					status: 503,
+					body: { error: "Syslog unavailable" }
+				};
+				return {
+					globalDebug: syslog.severityEnabled("DEBUG"),
+					overrides: syslog.getDebugOverrides(),
+					expiresAt: syslog.getDebugOverrideExpiry()
+				};
+			}
+		},
+		{
+			path: "log/level",
+			method: "PATCH",
+			summary: "Turn targeted per-module debug on/off at runtime (prod-safe, auto-expiring, audited)",
+			handler: (request) => {
+				const syslog = kernel.syslog;
+				if (!syslog) return {
+					status: 503,
+					body: { error: "Syslog unavailable" }
+				};
+				const body = request.body ?? {};
+				if (typeof body.module !== "string" || body.module.length === 0) return {
+					status: 400,
+					body: { error: "Missing 'module' (per-module debug only)" }
+				};
+				const module = body.module;
+				if (body.level === "off" || body.level === null || body.level === "") {
+					const cleared = syslog.clearDebugOverride(module);
+					auditLogLevelChange(kernel, request, module, "clear", null, null);
+					return {
+						ok: true,
+						module,
+						cleared,
+						overrides: syslog.getDebugOverrides()
+					};
+				}
+				if (typeof body.level !== "string" && typeof body.level !== "number") return {
+					status: 400,
+					body: { error: "Missing 'level'" }
+				};
+				const level = Syslog.severityFromInput(body.level);
+				if (level === null) return {
+					status: 422,
+					body: {
+						error: "Invalid 'level'",
+						level: body.level
+					}
+				};
+				const reqTtl = typeof body.ttlMs === "number" && body.ttlMs > 0 ? body.ttlMs : DEFAULT_DEBUG_TTL_MS;
+				const ttlMs = Math.min(reqTtl, MAX_DEBUG_TTL_MS);
+				syslog.setDebugOverride(module, level, ttlMs);
+				auditLogLevelChange(kernel, request, module, "set", level, ttlMs);
+				return {
+					ok: true,
+					module,
+					level,
+					ttlMs,
+					overrides: syslog.getDebugOverrides()
+				};
+			}
+		},
+		{
+			path: "module/{name}",
+			summary: "Detail of one module by key (http, framework, … or core)",
+			handler: async (request) => {
+				const key = request.params.name;
+				if (key === CORE_KEY) {
+					const core = await readCoreInfo();
+					return {
+						key: CORE_KEY,
+						name: core.name,
+						version: core.version,
+						isApp: false,
+						path: relPath(core.path),
+						dependencies: core.dependencies,
+						services: [],
+						config: {},
+						configSchema: null,
+						docsCount: await countModuleDocs(core.path),
+						symbolsCount: (await listModuleSymbols(CORE_PACKAGE)).length,
+						coverageLines: (await readCoverage(core.path)).total?.lines ?? null
+					};
+				}
+				const mod = kernel.getModules()[key];
+				if (!mod) return {
+					status: 404,
+					body: {
+						error: "Module not found",
+						key,
+						available: docKeys()
+					}
+				};
+				const services = mod.getServiceNames().map((sname) => ({
+					name: sname,
+					class: mod.get(sname)?.constructor?.name ?? null
+				}));
+				const cfg = computeConfigEntry(key, mod, runtimeEdited.get(key));
+				return {
+					key,
+					name: cfg.name,
+					version: mod.getModuleVersion?.() ?? null,
+					isApp: cfg.isApp,
+					path: relPath(mod.path),
+					dependencies: mod.getDependencies?.() ?? [],
+					services,
+					config: cfg.config,
+					configSchema: cfg.configSchema,
+					provenance: cfg.provenance,
+					seg: cfg.seg,
+					envKeys: cfg.envKeys,
+					docsCount: await countModuleDocs(mod.path),
+					symbolsCount: (await listModuleSymbols(cfg.name)).length,
+					coverageLines: (await readCoverage(mod.path)).total?.lines ?? null
+				};
+			}
+		},
+		{
+			path: "module/{name}/dependencies",
+			summary: "Module dependencies with installed versions",
+			handler: async (request) => {
+				const target = resolveTarget(request.params.name);
+				if (!target) return {
+					status: 404,
+					body: {
+						error: "Module not found",
+						key: request.params.name,
+						available: docKeys()
+					}
+				};
+				return {
+					key: request.params.name,
+					deps: await readDependencies(target.path)
+				};
+			}
+		},
+		{
+			path: "module/{name}/dependencies/outdated",
+			summary: "Check external dependencies for updates (npm registry)",
+			handler: async (request) => {
+				const target = resolveTarget(request.params.name);
+				if (!target) return {
+					status: 404,
+					body: {
+						error: "Module not found",
+						key: request.params.name,
+						available: docKeys()
+					}
+				};
+				const deps = await readDependencies(target.path);
+				return {
+					key: request.params.name,
+					outdated: await checkOutdated(deps)
+				};
+			}
+		},
+		{
+			path: "module/{name}/docs",
+			summary: "Documentation index of one module (markdown in <module>/docs)",
+			handler: async (request) => {
+				const key = request.params.name;
+				const dir = resolveDocDir(key);
+				if (!dir) return {
+					status: 404,
+					body: {
+						error: "Module not found",
+						key,
+						available: docKeys()
+					}
+				};
+				return {
+					key,
+					docs: await listModuleDocs(dir)
+				};
+			}
+		},
+		{
+			path: "module/{name}/docs/{slug}",
+			summary: "Raw markdown of one module doc by slug",
+			handler: async (request) => {
+				const key = request.params.name;
+				const dir = resolveDocDir(key);
+				if (!dir) return {
+					status: 404,
+					body: {
+						error: "Module not found",
+						key,
+						available: docKeys()
+					}
+				};
+				const doc = await readModuleDoc(dir, request.params.slug);
+				if (!doc) return {
+					status: 404,
+					body: {
+						error: "Doc not found",
+						key,
+						slug: request.params.slug,
+						available: (await listModuleDocs(dir)).map((d) => d.slug)
+					}
+				};
+				const wanted = typeof request.query.section === "string" ? request.query.section : "";
+				if (wanted !== "") {
+					const section = extractMarkdownSection(doc.markdown, wanted);
+					if (!section) return {
+						status: 404,
+						body: {
+							error: "Section not found",
+							key,
+							slug: doc.slug,
+							section: wanted,
+							outline: outlineMarkdown(doc.markdown)
+						}
+					};
+					return {
+						...doc,
+						section: section.title,
+						markdown: section.markdown
+					};
+				}
+				if (request.query.outline !== void 0) {
+					const { markdown, ...rest } = doc;
+					return {
+						...rest,
+						key,
+						chars: markdown.length,
+						outline: outlineMarkdown(markdown)
+					};
+				}
+				return doc;
+			}
+		},
+		{
+			path: "docs",
+			summary: "Documentation index across every loaded module",
+			handler: async () => {
+				const modules = [];
+				for (const target of docTargets()) {
+					const docs = await listModuleDocs(target.path);
+					if (docs.length > 0) modules.push({
+						key: target.key,
+						docs
+					});
+				}
+				return {
+					total: modules.reduce((sum, m) => sum + m.docs.length, 0),
+					modules
+				};
+			}
+		},
+		{
+			path: "docs/search",
+			summary: "Full-text search across every loaded module's documentation",
+			handler: async (request) => {
+				const raw = request.query.q;
+				const q = typeof raw === "string" ? raw : "";
+				if (q.trim() === "") return {
+					status: 400,
+					body: {
+						error: "Missing query parameter: q",
+						hint: "ex. /nodefony/kernel/api/docs/search?q=session+redis"
+					}
+				};
+				const limit = Number.parseInt(String(request.query.limit ?? ""), 10);
+				return searchModuleDocs(docTargets(), q, { limit: Number.isFinite(limit) && limit > 0 ? limit : void 0 });
+			}
+		},
+		{
+			path: "module/{name}/symbol/{symbol}",
+			summary: "Declaration (signature + TSDoc) of one exported symbol",
+			handler: async (request) => {
+				const key = request.params.name;
+				const modulePath = resolveTarget(key)?.path ?? resolvePackageDir(key);
+				if (!modulePath) return {
+					status: 404,
+					body: {
+						error: "Module not found",
+						key,
+						available: docKeys()
+					}
+				};
+				const symbol = request.params.symbol;
+				const found = await readSymbolDeclaration(modulePath, symbol);
+				if (!found) return {
+					status: 404,
+					body: {
+						error: "Symbol declaration not found",
+						key,
+						symbol,
+						hint: "le module publie-t-il ses types (dist/types) ?"
+					}
+				};
+				return {
+					key,
+					symbol,
+					...found
+				};
+			}
+		},
+		{
+			path: "module/{name}/symbols",
+			summary: "Exported TS symbols + TSDoc descriptions (.ai/symbols.json)",
+			handler: async (request) => {
+				const key = request.params.name;
+				const target = resolveTarget(key);
+				if (!target) return {
+					status: 404,
+					body: {
+						error: "Module not found",
+						key,
+						available: docKeys()
+					}
+				};
+				return {
+					key,
+					package: target.pkg,
+					symbols: await listModuleSymbols(target.pkg)
+				};
+			}
+		},
+		{
+			path: "module/{name}/coverage",
+			summary: "Latest test coverage report (vitest json-summary)",
+			handler: async (request) => {
+				const key = request.params.name;
+				const target = resolveTarget(key);
+				if (!target) return {
+					status: 404,
+					body: {
+						error: "Module not found",
+						key,
+						available: docKeys()
+					}
+				};
+				return {
+					key,
+					...await readCoverage(target.path)
+				};
+			}
+		},
+		{
+			path: "module/{name}/tests",
+			summary: "List test files of one module",
+			handler: async (request) => {
+				const key = request.params.name;
+				const target = resolveTarget(key);
+				if (!target) return {
+					status: 404,
+					body: {
+						error: "Module not found",
+						key,
+						available: docKeys()
+					}
+				};
+				return {
+					key,
+					devMode: kernel.environment === "development" || Boolean(kernel.debug),
+					files: await listTestFiles(target.path),
+					groups: await listTestGroups(target.path)
+				};
+			}
+		},
+		{
+			path: "module/{name}/test/run",
+			method: "POST",
+			summary: "Start a test run (dev only) — 1 file or whole suite → jobId",
+			handler: (request) => {
+				if (!devGuard()) return {
+					status: 403,
+					body: { error: "Test runner disabled outside development" }
+				};
+				const key = request.params.name;
+				const target = resolveTarget(key);
+				if (!target) return {
+					status: 404,
+					body: {
+						error: "Module not found",
+						key,
+						available: docKeys()
+					}
+				};
+				const body = request.body ?? {};
+				let file;
+				if (typeof body.file === "string" && body.file) {
+					if (body.file.includes("..") || body.file.startsWith("-") || !body.file.endsWith(".test.ts")) return {
+						status: 400,
+						body: {
+							error: "Invalid test file",
+							file: body.file
+						}
+					};
+					file = body.file;
+				}
+				const jobId = randomUUID();
+				testJobs.set(jobId, {
+					status: "running",
+					startedAt: Date.now()
+				});
+				if (testJobs.size > 16) {
+					const oldest = [...testJobs.entries()].sort((a, b) => a[1].startedAt - b[1].startedAt)[0];
+					if (oldest) testJobs.delete(oldest[0]);
+				}
+				runModuleTests(target.path, file).then((result) => testJobs.set(jobId, {
+					status: "done",
+					startedAt: Date.now(),
+					result
+				}), (e) => testJobs.set(jobId, {
+					status: "done",
+					startedAt: Date.now(),
+					result: {
+						ok: false,
+						code: null,
+						passed: 0,
+						failed: 0,
+						durationMs: 0,
+						output: String(e),
+						mode: ""
+					}
+				}));
+				return {
+					key,
+					jobId,
+					running: true
+				};
+			}
+		},
+		{
+			path: "module/{name}/test/run",
+			method: "GET",
+			summary: "Poll a test run by ?jobId",
+			handler: (request) => {
+				const jobId = String(request.query.jobId ?? "");
+				const job = jobId ? testJobs.get(jobId) : void 0;
+				if (!job) return {
+					status: 404,
+					body: {
+						error: "Unknown jobId",
+						jobId
+					}
+				};
+				return {
+					jobId,
+					done: job.status === "done",
+					...job.result
+				};
+			}
+		}
+	];
+	return {
+		adminNamespace: "kernel",
+		adminDescriptor: () => descriptor,
+		adminEndpoints: () => endpoints
+	};
+}
+//#endregion
+export { createKernelAdminApi, nodefonyPackageCandidates, safeConfig };