@nodefony/framework 10.0.0-beta.1 → 10.0.0-beta.3

package/dist/nodefony/src/KernelAdminApi.js

@@ -2,7 +2,7 @@ import { CORE_PACKAGE, checkOutdated, countModuleDocs, listModuleDocs, listModul
 import { getResolvedPath, navigateSchemaNode, nodeFlags, notEditableReason, recipeFor, validateLeafValue } from "./configMutation.js";
 import { createRequire } from "node:module";
 import { join } from "node:path";
-import { GitService, Syslog, aggregateProvenance, collectDevStatus, computeConfigProvenance, defaultAppConfig, extractJsonSchemaDefaults, extractMarkdownSection, flattenConfigSchema, getActiveLogDriver, listLogDrivers, outlineMarkdown, parseNfEnvOverrides, parseStoreManifest, readResolvedPath, withResolvedPath } from "nodefony";
+import { GitService, Syslog, aggregateProvenance, collectDevStatus, collectEnvShortcuts, computeConfigProvenance, defaultAppConfig, extractJsonSchemaDefaults, extractMarkdownSection, flattenConfigSchema, getActiveLogDriver, isFrameworkRepository, listLogDrivers, outlineMarkdown, parseNfEnvOverrides, parseStoreManifest, readResolvedPath, resumeSupervisor, runAppContributions, suspendSupervisor, withResolvedPath } from "nodefony";
 import { randomUUID } from "node:crypto";
 import { existsSync, readFileSync } from "node:fs";
 //#region nodefony/src/KernelAdminApi.ts
@@ -204,13 +204,23 @@ function computeConfigEntry(key, mod, runtimePaths) {
 	const isApp = mod.isApp ?? false;
 	const seg = computeSeg(pkg, isApp);
 	const envKeys = {};
+	const shortcutPaths = [];
+	if (!isApp) for (const s of collectEnvShortcuts(schema)) {
+		const raw = process.env[s.env];
+		const file = process.env[`${s.env}_FILE`];
+		const fromFile = file !== void 0 && file !== "";
+		if ((raw === void 0 || raw === "") && !fromFile) continue;
+		const dotted = s.path.join(".").toLowerCase();
+		envKeys[dotted] = fromFile ? `${s.env}_FILE` : s.env;
+		shortcutPaths.push(dotted);
+	}
 	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(".")));
+		const envPaths = /* @__PURE__ */ new Set([...shortcutPaths, ...parseNfEnvOverrides(process.env).filter((o) => o.moduleSeg === seg).map((o) => o.path.join("."))]);
 		provenance = computeConfigProvenance(opts, extractJsonSchemaDefaults(schema), envPaths);
 	}
 	if (provenance && runtimePaths?.size) {
@@ -235,7 +245,7 @@ function actorLabel(user) {
 	if (typeof u.getUserIdentifier === "function") try {
 		return u.getUserIdentifier();
 	} catch {}
-	return u.username ?? u.email ?? (u.id != null ? String(u.id) : null);
+	return u.identifier ?? u.email ?? (u.id != null ? String(u.id) : null);
 }
 /**
 * Journalise une mutation de config (catégorie `config`) **si** le service d'audit
@@ -337,6 +347,33 @@ function nodefonyPackageCandidates(name) {
 	const inScope = (pkg) => pkg === "nodefony" || pkg === "@nodefony/core" || pkg.startsWith("@nodefony/");
 	return (name.includes("/") ? [name] : [`@nodefony/${name}`, name]).filter(inScope);
 }
+/** Refus de `scaffold` hors développement. */
+const scaffoldRefused = () => ({
+	status: 403,
+	body: { error: "scaffold:sync is disabled outside development" }
+});
+/**
+* La réponse de `scaffold` : les rapports tels quels, et les totaux qu'un écran
+* affiche sans les recompter.
+*
+* @param reports - le rendu de `runAppContributions`
+* @param dryRun - `true` pour un plan
+* @returns le corps de la réponse
+*/
+function scaffoldPayload(reports, dryRun) {
+	const sum = (pick) => reports.reduce((n, r) => n + pick(r), 0);
+	return {
+		dryRun,
+		reports,
+		totals: {
+			written: sum((r) => r.written.length),
+			updated: sum((r) => r.updated.length),
+			outdated: sum((r) => r.outdated.length),
+			modified: sum((r) => r.modified.length),
+			failed: sum((r) => r.error === null ? 0 : 1)
+		}
+	};
+}
 function createKernelAdminApi(kernel) {
 	const descriptor = {
 		label: "Kernel",
@@ -376,6 +413,8 @@ function createKernelAdminApi(kernel) {
 	* @param key - clé courte (`http`) ou nom de paquet (`@nodefony/redis`).
 	* @returns le dossier à lire, ou `null`.
 	*/
+	let frameworkRepository = null;
+	const inFrameworkRepository = () => frameworkRepository ??= isFrameworkRepository(kernel.path);
 	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.
@@ -538,6 +577,30 @@ function createKernelAdminApi(kernel) {
 				git: GitService.read()
 			})
 		},
+		{
+			path: "scaffold",
+			summary: "Files delivered by installed packages (dev only) — what `scaffold:sync --update` would do",
+			handler: async () => {
+				if (!devGuard()) return scaffoldRefused();
+				return scaffoldPayload(await runAppContributions(REPO_ROOT, true, true), true);
+			}
+		},
+		{
+			path: "scaffold/sync",
+			method: "POST",
+			summary: "Run `scaffold:sync` (dev only) — body `{ update?: boolean }`",
+			handler: async (request) => {
+				if (!devGuard()) return scaffoldRefused();
+				const body = request.body;
+				const update = typeof body === "object" && body !== null && "update" in body && body.update === true;
+				suspendSupervisor(REPO_ROOT, "synchronisation des fichiers livrés", update ? "scaffold:sync --update" : "scaffold:sync");
+				try {
+					return scaffoldPayload(await runAppContributions(REPO_ROOT, false, update), false);
+				} finally {
+					resumeSupervisor(REPO_ROOT);
+				}
+			}
+		},
 		{
 			path: "processes",
 			summary: "Dev process topology (supervisor → server → Vite) + server ports — `nodefony status` over the data plane",
@@ -927,7 +990,7 @@ function createKernelAdminApi(kernel) {
 						services: [],
 						config: {},
 						configSchema: null,
-						docsCount: await countModuleDocs(core.path),
+						docsCount: await countModuleDocs(core.path, inFrameworkRepository()),
 						symbolsCount: (await listModuleSymbols(CORE_PACKAGE)).length,
 						coverageLines: (await readCoverage(core.path)).total?.lines ?? null
 					};
@@ -959,7 +1022,7 @@ function createKernelAdminApi(kernel) {
 					provenance: cfg.provenance,
 					seg: cfg.seg,
 					envKeys: cfg.envKeys,
-					docsCount: await countModuleDocs(mod.path),
+					docsCount: await countModuleDocs(mod.path, inFrameworkRepository()),
 					symbolsCount: (await listModuleSymbols(cfg.name)).length,
 					coverageLines: (await readCoverage(mod.path)).total?.lines ?? null
 				};
@@ -1020,7 +1083,7 @@ function createKernelAdminApi(kernel) {
 				};
 				return {
 					key,
-					docs: await listModuleDocs(dir)
+					docs: await listModuleDocs(dir, false, inFrameworkRepository())
 				};
 			}
 		},
@@ -1038,14 +1101,14 @@ function createKernelAdminApi(kernel) {
 						available: docKeys()
 					}
 				};
-				const doc = await readModuleDoc(dir, request.params.slug ?? "");
+				const doc = await readModuleDoc(dir, request.params.slug ?? "", inFrameworkRepository());
 				if (!doc) return {
 					status: 404,
 					body: {
 						error: "Doc not found",
 						key,
 						slug: request.params.slug,
-						available: (await listModuleDocs(dir)).map((d) => d.slug)
+						available: (await listModuleDocs(dir, false, inFrameworkRepository())).map((d) => d.slug)
 					}
 				};
 				const wanted = typeof request.query.section === "string" ? request.query.section : "";
@@ -1085,7 +1148,7 @@ function createKernelAdminApi(kernel) {
 			handler: async () => {
 				const modules = [];
 				for (const target of docTargets()) {
-					const docs = await listModuleDocs(target.path);
+					const docs = await listModuleDocs(target.path, false, inFrameworkRepository());
 					if (docs.length > 0) modules.push({
 						key: target.key,
 						docs
@@ -1111,7 +1174,10 @@ function createKernelAdminApi(kernel) {
 					}
 				};
 				const limit = Number.parseInt(String(request.query.limit ?? ""), 10);
-				return searchModuleDocs(docTargets(), q, { limit: Number.isFinite(limit) && limit > 0 ? limit : void 0 });
+				return searchModuleDocs(docTargets(), q, {
+					limit: Number.isFinite(limit) && limit > 0 ? limit : void 0,
+					frameworkRepository: inFrameworkRepository()
+				});
 			}
 		},
 		{

package/dist/nodefony/src/Resolver.js

@@ -1,6 +1,7 @@
 import { guardSingletonState, isDevelopment } from "./singletonGuard.js";
 import { buildParamArgs, computeActionMeta, resolveActionMeta, resolveSessionIntent } from "../decorators/routerDecorators.js";
 import { computeFingerprint, evaluateIdempotency, isMutationMethod, resolveIdempotencyKey, resolveIdentity } from "./idempotency.js";
+import { authenticationShortfall, stepUpChallenge } from "./requireAuthentication.js";
 import { RequestContext, finallyMaybe, identityHint, isArray, isPlainObject, isPromise, nodefonyError, thenMaybe, typeOf } from "nodefony";
 import { Http2Response, HttpResponse, WebsocketResponse } from "@nodefony/http";
 //#region nodefony/src/Resolver.ts
@@ -78,8 +79,8 @@ var Resolver = class {
 		this.context = context;
 		this.injector = context.container?.get("injector") ?? null;
 	}
-	match(route, context, cleanPath) {
-		const match = route.match(context, cleanPath, this.methodOverride ?? void 0);
+	match(route, context, cleanPath, literal) {
+		const match = route.match(context, cleanPath, this.methodOverride ?? void 0, literal);
 		if (match) {
 			this.variables = match;
 			this.route = route;
@@ -180,10 +181,20 @@ var Resolver = class {
 	* `instanceof` au message suivant — le hub était RÉINSTANCIÉ (DI +
 	* `initialize()`) à chaque frame qui suivait un `api.request`.
 	*
+	* Ni pour un `forward` sur une connexion WebSocket : son résolveur est neuf,
+	* pas une invocation par message, et réécrivait le pointeur que la poignée
+	* de main a posé — même réinstanciation à la frame suivante (#574). Une
+	* connexion garde le contrôleur qui l'a ouverte. Chemin froid : seulement
+	* quand un contrôleur est créé.
+	*
 	* @returns le controller reçu, pour enchaîner.
 	*/
 	_pinController(controller) {
-		if (!this.messageInvocation) this.context.container?.set("controller", controller);
+		if (this.messageInvocation) return controller;
+		const container = this.context.container;
+		if (!container) return controller;
+		if (this.context.method === "WEBSOCKET" && container.get("controller") !== null) return controller;
+		container.set("controller", controller);
 		return controller;
 	}
 	/**
@@ -263,6 +274,7 @@ var Resolver = class {
 	*   lookup, ni attente) ; sinon la promesse du verdict, rompue par un refus.
 	*/
 	_enforceActionSecurity(meta) {
+		if (meta.authentication !== null) return this._enforceStepUp(meta);
 		if (meta.security === null) return this._enforceAreaSecurity();
 		const granted = this._enforceSecurity(meta.security);
 		return meta.security.hasRoleClause ? granted : granted.then(() => this._enforceAreaSecurity());
@@ -385,7 +397,7 @@ var Resolver = class {
 		const store = context.container?.get("idempotencyStore");
 		const verdict = await evaluateIdempotency({
 			store,
-			identity: resolveIdentity(als?.user),
+			identity: resolveIdentity(),
 			clientKey: resolveIdempotencyKey(als?.idempotencyKey, httpReq?.headers?.["idempotency-key"]),
 			fingerprint: computeFingerprint([
 				this.route?.name ?? this.actionName,
@@ -639,6 +651,31 @@ var Resolver = class {
 	getResponseStatus() {
 		return this.context.response?.statusCode ?? 0;
 	}
+	/**
+	* `@RequireAuthentication` — les gardes d'autorisation d'abord (un rôle
+	* absent reste un 403 définitif : inutile de faire redemander une connexion à
+	* qui n'aura pas le droit), PUIS l'âge et les moyens de la connexion.
+	*
+	* Le refus est un 401 « step-up » (RFC 9470) : le `WWW-Authenticate` porte
+	* `error="insufficient_user_authentication"` et, quand la route fixe un âge,
+	* `max_age` — le client redemande une connexion au lieu de conclure à un
+	* accès fermé. Cold path : seules les routes décorées y passent.
+	*
+	* @throws nodefonyError 401 si la connexion est trop ancienne ou trop faible.
+	*/
+	async _enforceStepUp(meta) {
+		const requirement = meta.authentication;
+		if (requirement === null) return;
+		await this._enforceActionSecurity({
+			...meta,
+			authentication: null
+		});
+		const cause = authenticationShortfall(this.context.session ?? null, requirement, Date.now());
+		if (cause === null) return;
+		const response = this.context.response;
+		if (response !== null && "setHeader" in response) response.setHeader("WWW-Authenticate", stepUpChallenge(requirement));
+		throw new nodefonyError(identityHint(this.context.kernel) === null ? "Authentication required" : `Authentication required — ${cause}. Reconnectez-vous (\`@RequireAuthentication\` de la route).`, 401);
+	}
 };
 /** Statuts dont la réponse n'a, par définition, pas de corps (RFC 9110). */
 const NO_BODY_STATUS = /* @__PURE__ */ new Set([

package/dist/nodefony/src/Route.js

@@ -99,6 +99,32 @@ function replaceCallback(_match, slash, dot, key, capture, opt, _offset) {
 	}
 	throw new Error(`Bad path `);
 }
+/**
+* Exigences d'une route, l'option `method` versée dans `requirements.methods`.
+*
+* Seul `requirements.methods` restreint le match ; l'option `method` n'était
+* lue que pour l'affichage, si bien qu'une route « POST » servait toutes les
+* méthodes. Les deux déclarations s'UNISSENT, comme le font les décorateurs
+* `@Get`/`@Post` : déclarer n'élargit jamais en silence ni n'écrase.
+*
+* @param requirements - exigences déclarées (jamais mutées)
+* @param method - méthode(s) de l'option `method`
+* @returns les exigences à poser sur la route
+*/
+function withDeclaredMethod(requirements, method) {
+	if (method === void 0) return requirements ?? {};
+	const own = requirements?.methods;
+	const union = new Set(Array.isArray(method) ? method : [method]);
+	if (own !== void 0) for (const m of Array.isArray(own) ? own : [own]) union.add(m);
+	return {
+		...requirements,
+		methods: [...union]
+	};
+}
+/** Canal chiffré : `https` (HTTP) ou `wss` (WebSocket). */
+function isSecureScheme(scheme) {
+	return scheme === "https" || scheme === "wss";
+}
 var Route = class Route {
 	name;
 	path;
@@ -106,7 +132,6 @@ var Route = class Route {
 	classMethod;
 	prefix;
 	method;
-	schemes;
 	pattern;
 	variables = [];
 	/**
@@ -144,6 +169,8 @@ var Route = class Route {
 	* pas son rôle par défaut. Cf {@link RouteOptions.areaRoleExempt}.
 	*/
 	areaRoleExempt = false;
+	/** Route de repli, résolue après toutes les autres. Cf {@link RouteOptions.fallback}. */
+	fallback = false;
 	/**
 	* P2.9 — Cache mémoïsé : l'action attend-elle le **flux brut** du body
 	* (`@Body({ stream:true })`) ? `undefined` = pas encore calculé (résolu au 1er
@@ -177,9 +204,10 @@ var Route = class Route {
 			this.method = obj.method;
 			this.setHostname(obj.host);
 			this.setDefaults(obj.defaults);
-			this.requirements = obj.requirements ?? {};
+			this.requirements = withDeclaredMethod(obj.requirements, obj.method);
 			this.bypassFirewall = obj.bypassFirewall ?? false;
 			this.areaRoleExempt = obj.areaRoleExempt ?? false;
+			this.fallback = obj.fallback ?? false;
 			this.compile();
 		}
 		this.generateId();
@@ -203,10 +231,29 @@ var Route = class Route {
 		if (!reqUrl) return;
 		return stripTrailingSlashes(reqUrl.pathname);
 	}
-	match(context, cleanPath, methodOverride) {
+	/**
+	* Confronte la requête à cette route : chemin, hôte, puis exigences.
+	*
+	* @param context - contexte HTTP/WS courant.
+	* @param cleanPath - pathname déjà normalisé par l'appelant (sinon recalculé).
+	* @param methodOverride - méthode logique du pont WS-RPC (cf `Resolver`).
+	* @param literal - l'appelant GARANTIT que le chemin de la route ne porte
+	*   aucune syntaxe de motif (`{}`, `*`…) — c'est le cas d'une route trouvée
+	*   par l'index des littérales du `Router`. Le motif n'est alors pas exécuté
+	*   quand le chemin est identique à la lettre.
+	* @returns les valeurs capturées (tableau + accès par nom), ou `null`/`undefined`
+	*   quand le chemin ne correspond pas.
+	* @throws 403/405/1002 quand le chemin correspond mais pas l'hôte ou les exigences.
+	*/
+	match(context, cleanPath, methodOverride, literal) {
 		let res;
 		if (context.request && this.pattern) {
 			const url = cleanPath ?? Route.cleanPathname(context);
+			if (literal === true && url === this.path && !this.#hasPositionalDefaults()) {
+				this.matchHostname(context);
+				this.matchRequirements(context, methodOverride);
+				return [];
+			}
 			if (url !== void 0) res = url.match(this.pattern);
 		}
 		if (!res) return res;
@@ -307,6 +354,10 @@ var Route = class Route {
 			if (compiled) (this.varRegexp ??= Object.create(null))[k] = compiled;
 		}
 	}
+	#hasPositionalDefaults() {
+		for (const def in this.defaults) if (def !== "controller") return true;
+		return false;
+	}
 	hydrateDefaultParameters(res) {
 		if (this.variables.length) for (let i = 0; i < this.variables.length; i++) {
 			const name = this.variables[i];
@@ -343,7 +394,8 @@ var Route = class Route {
 		const action = this.classMethod || this.name;
 		const mod = this.module?.name ? `@${this.module.name}/` : "";
 		const auth = this.bypassFirewall ? "  (no auth)" : this.areaRoleExempt ? "  (hors rôle de zone)" : "";
-		return `${method} ${this.path} → ${mod}${ctrl}.${action}${auth}`;
+		const fallback = this.fallback ? "  (repli)" : "";
+		return `${method} ${this.path} → ${mod}${ctrl}.${action}${auth}${fallback}`;
 	}
 	toObject() {
 		return {
@@ -353,10 +405,11 @@ var Route = class Route {
 			host: this.host,
 			controller: this.defaults.controller,
 			filePath: this.filePath,
-			schemes: this.schemes,
+			schemes: this.requirements.scheme,
 			variables: this.variables,
 			bypassFirewall: this.bypassFirewall,
-			areaRoleExempt: this.areaRoleExempt
+			areaRoleExempt: this.areaRoleExempt,
+			fallback: this.fallback
 		};
 	}
 	setDefaults(arg) {
@@ -436,6 +489,13 @@ var Route = class Route {
 		return Object.keys(this.requirements).length;
 	}
 	matchRequirements(context, methodOverride) {
+		if (this.requirements.methods === void 0 && (methodOverride !== void 0 || context.method === "WEBSOCKET")) {
+			const error = new HttpError(`Method ${methodOverride ?? "WEBSOCKET"} Not Allowed`);
+			error.code = 405;
+			error.type = "method";
+			error.allow = "";
+			throw error;
+		}
 		if (this.hasRequirements()) for (const i in this.requirements) switch (i) {
 			case "methods":
 				if (!this.methodsSet) throw new Error(`Bad config route method : ${String(this.requirements.methods)}`);
@@ -457,6 +517,16 @@ var Route = class Route {
 					throw error;
 				}
 				break;
+			case "scheme": {
+				const required = this.requirements.scheme;
+				if (required !== void 0 && isSecureScheme(required) !== isSecureScheme(context.scheme)) {
+					const error = new HttpError(`Scheme ${context.scheme} Forbidden for this route : ${required} required`);
+					error.code = 403;
+					error.type = "scheme";
+					throw error;
+				}
+				break;
+			}
 			case "domain": break;
 			case "protocol": if (context.method === "WEBSOCKET") {
 				const requirement = this.requirements[i];

package/dist/nodefony/src/SecurityApiController.js

@@ -0,0 +1,24 @@
+import Controller from "./Controller.js";
+//#region nodefony/src/SecurityApiController.ts
+const NO_STORE = { "cache-control": "no-store" };
+/**
+* Base des contrôleurs d'authentification (`/nodefony/security/api/*`) : toute
+* réponse JSON part en `Cache-Control: no-store`.
+*
+* Ces réponses portent une identité, un jeton, un secret affiché une seule
+* fois (clé API, secret TOTP, codes de récupération) ou leur refus. Un cookie
+* ou un en-tête dans la requête n'empêche pas un cache partagé de STOCKER la
+* réponse (RFC 9111 §3) ; RFC 6749 §5.1 exige `no-store` sur un jeton. La règle
+* vit ici, une fois : une action ajoutée à un contrôleur héritier ne peut pas
+* l'oublier. Un en-tête passé par l'action garde la priorité.
+*/
+var SecurityApiController = class extends Controller {
+	renderJson(obj, status, headers) {
+		return super.renderJson(obj, status, {
+			...NO_STORE,
+			...headers
+		});
+	}
+};
+//#endregion
+export { SecurityApiController as default };

package/dist/nodefony/src/docsReader.js

@@ -1,5 +1,5 @@
 import { basename, dirname, extname, join } from "node:path";
-import { findProjectRoot, resolveSymbolsFile } from "nodefony";
+import { findProjectRoot, isDocVisible, packageManagerCommandLines, packageManagerExecArgs, portableSpawn, readDocScope, readSymbolsGraph, resolvePackageManager } from "nodefony";
 import { existsSync } from "node:fs";
 import { promisify } from "node:util";
 import { readFile, readdir, stat } from "node:fs/promises";
@@ -97,11 +97,19 @@ async function gitLastUpdated(file) {
 		return null;
 	}
 }
-/** Construit un `DocSummary` à partir du contenu brut d'un `.md`. */
-async function summarize(docsDir, fileName, withGit) {
+/**
+* La page se sert-elle dans ce décor ? Portée lue dans `publish` par la règle
+* du cœur (`readDocScope`/`isDocVisible`) — la même que le portail et le site.
+*/
+function servable(data, frameworkRepository) {
+	return isDocVisible(readDocScope(data.publish), frameworkRepository);
+}
+/** Construit un `DocSummary` à partir du contenu brut d'un `.md` — `null` si la page n'est pas servie ici. */
+async function summarize(docsDir, fileName, withGit, frameworkRepository) {
 	const slug = basename(fileName, extname(fileName));
 	const full = join(docsDir, fileName);
 	const { data, body } = parseFrontmatter(await readFile(full, "utf8"));
+	if (!servable(data, frameworkRepository)) return null;
 	const title = docTitle(data, body, slug);
 	return {
 		slug,
@@ -121,7 +129,7 @@ async function summarize(docsDir, fileName, withGit) {
 * @param modulePath - chemin disque du module (`Module.path`).
 * @returns liste triée (vide si le dossier `docs/` est absent).
 */
-async function listModuleDocs(modulePath, withGit = false) {
+async function listModuleDocs(modulePath, withGit = false, frameworkRepository = false) {
 	const docsDir = join(modulePath, "docs");
 	let entries;
 	try {
@@ -130,21 +138,34 @@ async function listModuleDocs(modulePath, withGit = false) {
 		return [];
 	}
 	const mdFiles = entries.filter((f) => f.toLowerCase().endsWith(".md"));
-	return (await Promise.all(mdFiles.map((f) => summarize(docsDir, f, withGit)))).sort((a, b) => a.order - b.order || a.slug.localeCompare(b.slug));
+	return (await Promise.all(mdFiles.map((f) => summarize(docsDir, f, withGit, frameworkRepository)))).filter((d) => d !== null).sort((a, b) => a.order - b.order || a.slug.localeCompare(b.slug));
 }
 /**
-* Comptage rapide des docs (`*.md`) d'un module — readdir seul, sans lire/parser
-* ni `git`. Pour les KPI/overview (`docsCount`) où seul le nombre importe.
+* Comptage des docs SERVIES d'un module, sans `git` — pour les KPI/overview
+* (`docsCount`) où seul le nombre importe. Le frontmatter est lu : le compte
+* suit la même portée (`publish`) que la liste, sinon le KPI annonce des pages
+* que l'onglet Docs refuse d'ouvrir.
 *
 * @param modulePath - chemin disque du module (`Module.path`).
-* @returns nombre de fichiers `.md` dans `<modulePath>/docs/` (0 si absent).
+* @param frameworkRepository - vrai dans le dépôt du framework (pages `core` servies).
+* @returns nombre de pages servies dans `<modulePath>/docs/` (0 si absent).
 */
-async function countModuleDocs(modulePath) {
+async function countModuleDocs(modulePath, frameworkRepository = false) {
+	const docsDir = join(modulePath, "docs");
+	let entries;
 	try {
-		return (await readdir(join(modulePath, "docs"))).filter((f) => f.toLowerCase().endsWith(".md")).length;
+		entries = await readdir(docsDir);
 	} catch {
 		return 0;
 	}
+	return (await Promise.all(entries.filter((f) => f.toLowerCase().endsWith(".md")).map(async (f) => {
+		try {
+			const { data } = parseFrontmatter(await readFile(join(docsDir, f), "utf8"));
+			return servable(data, frameworkRepository);
+		} catch {
+			return false;
+		}
+	}))).filter(Boolean).length;
 }
 /**
 * Lit une doc module par slug : frontmatter + corps markdown brut.
@@ -154,7 +175,7 @@ async function countModuleDocs(modulePath) {
 *
 * @returns `null` si slug invalide ou fichier absent.
 */
-async function readModuleDoc(modulePath, slug) {
+async function readModuleDoc(modulePath, slug, frameworkRepository = false) {
 	if (!SLUG_RE.test(slug)) return null;
 	const full = join(modulePath, "docs", `${slug}.md`);
 	let raw;
@@ -164,6 +185,7 @@ async function readModuleDoc(modulePath, slug) {
 		return null;
 	}
 	const { data, body } = parseFrontmatter(raw);
+	if (!servable(data, frameworkRepository)) return null;
 	return {
 		slug,
 		frontmatter: data,
@@ -276,9 +298,10 @@ async function searchModuleDocs(targets, query, options = {}) {
 			} catch {
 				continue;
 			}
-			scanned += 1;
 			const slug = basename(fileName, extname(fileName));
 			const { data, body } = parseFrontmatter(raw);
+			if (!servable(data, options.frameworkRepository ?? false)) continue;
+			scanned += 1;
 			const title = docTitle(data, body, slug);
 			const foldedTitle = fold(`${title} ${typeof data.navTitle === "string" && data.navTitle.trim() ? data.navTitle.trim() : ""} ${slug}`);
 			const lines = body.split("\n");
@@ -347,15 +370,9 @@ async function searchModuleDocs(targets, query, options = {}) {
 * @returns symboles exportés triés par kind puis nom (vide si fichier absent).
 */
 async function listModuleSymbols(packageName) {
-	const file = resolveSymbolsFile(process.cwd());
-	if (file === null) return [];
-	let parsed;
-	try {
-		parsed = JSON.parse(await readFile(file, "utf8"));
-	} catch {
-		return [];
-	}
-	const symbols = parsed.symbols ?? {};
+	const graph = readSymbolsGraph(process.cwd());
+	if (graph === null) return [];
+	const symbols = graph.symbols;
 	const out = [];
 	for (const sym of Object.values(symbols)) {
 		if (sym.module !== packageName || sym.exported !== true) continue;
@@ -653,50 +670,54 @@ async function listTestGroups(modulePath) {
 *   config du module (la liste `reporter` dupliquée par module divergeait).
 * - sinon (cœur : monocart, pas de `vitest.config.ts`) → `npm run coverage`.
 *
+* Le binaire et le script passent par le gestionnaire de paquets du PROJET :
+* `npx` n'existe pas chez bun, et sous pnpm il chercherait hors de l'arbre que
+* le verrou décrit.
+*
 * @param modulePath - racine du module (où vit `vitest.config.ts`)
 * @param file - chemin relatif d'UN fichier de test, déjà validé par l'appelant
+* @param manager - gestionnaire du projet ; défaut : résolu depuis la racine
+*   de l'application qui contient le module
 * @returns commande, arguments en tableau (spawn sans shell) et libellé du mode
 */
-function testRunCommand(modulePath, file) {
+function testRunCommand(modulePath, file, manager = resolvePackageManager({ dir: findProjectRoot(modulePath) ?? modulePath }).name) {
 	const hasVitest = existsSync(join(modulePath, "vitest.config.ts"));
 	if (file && hasVitest) return {
-		cmd: "npx",
-		args: [
-			"vitest",
-			"run",
-			file
-		],
+		cmd: manager,
+		args: packageManagerExecArgs(manager, "vitest", ["run", file]),
 		mode: `vitest run ${file}`
 	};
 	if (hasVitest) return {
-		cmd: "npx",
-		args: [
-			"vitest",
+		cmd: manager,
+		args: packageManagerExecArgs(manager, "vitest", [
 			"run",
 			"--coverage",
 			"--coverage.reporter=text-summary",
 			"--coverage.reporter=json-summary",
 			"--coverage.reporter=lcov",
 			"--coverage.reportsDirectory=.coverage"
-		],
+		]),
 		mode: "vitest run --coverage (reporters forcés)"
 	};
 	return {
-		cmd: "npm",
+		cmd: manager,
 		args: ["run", "coverage"],
-		mode: "npm run coverage (suite complète)"
+		mode: `${packageManagerCommandLines(manager).run("coverage")} (suite complète)`
 	};
 }
 /**
 * Lance les tests d'un module et renvoie un résumé (pass/fail/durée + tail).
 *
-* - 1 fichier (module vitest) → `npx vitest run <file>` (rapide, pass/fail).
-* - sinon → `npm run coverage` (suite complète + refresh coverage ; marche
-*   pour vitest comme pour monocart/core).
+* - 1 fichier (module vitest) → `vitest run <file>` (rapide, pass/fail).
+* - sinon → le script `coverage` (suite complète + refresh coverage ; marche
+*   pour vitest comme pour le cœur).
+* Les deux par le gestionnaire du projet (cf {@link testRunCommand}).
 *
 * ⚠️ EXÉCUTE un process — appelé UNIQUEMENT derrière le garde dev-only de
-* l'endpoint (cf KernelAdminApi). spawn sans shell + args en tableau (pas
-* d'injection shell). `file` validé en amont (suffixe .test.ts, pas de `..`).
+* l'endpoint (cf KernelAdminApi). `portableSpawn` : jamais de `shell`, args
+* en tableau (pas d'injection), et le `.cmd` du gestionnaire se lance sous
+* Windows — un `spawn("npx")` nu y rendait `ENOENT`. `file` validé en amont
+* (suffixe .test.ts, pas de `..`).
 */
 function runModuleTests(modulePath, file) {
 	const { cmd, args, mode } = testRunCommand(modulePath, file);
@@ -709,9 +730,11 @@ function runModuleTests(modulePath, file) {
 		};
 		let child;
 		try {
-			child = spawn(cmd, args, {
+			const run = portableSpawn(cmd, args);
+			child = spawn(run.file, run.args, {
 				cwd: modulePath,
-				env: process.env
+				env: process.env,
+				windowsVerbatimArguments: run.windowsVerbatimArguments
 			});
 		} catch (e) {
 			return resolve({