@nodefony/framework 10.0.0-alpha.1

package/dist/types/nodefony/interfaces/IAdminBroker.d.ts

@@ -0,0 +1,79 @@
+import type { IAdminEndpoint, IAdminRegistry } from "nodefony";
+/**
+ * Entrée résolue d'un endpoint admin — couple le producteur, sa définition et
+ * le chemin absolu monté. Renvoyé par l'introspection du broker (utile à
+ * l'auto-doc Studio et aux tests).
+ */
+export interface IAdminRoute {
+    /** Nom unique de la route framework (clé de dispatch O(1)). */
+    name: string;
+    /** Namespace du producteur (`IAdminApi.adminNamespace`). */
+    namespace: string;
+    /** Chemin absolu monté, ex `/nodefony/http/api/sessions`. */
+    path: string;
+    /** Méthode HTTP effective (défaut résolu). */
+    method: string;
+    /** Rôle effectif requis (défaut résolu). */
+    role: string;
+    /** Définition d'origine. */
+    endpoint: IAdminEndpoint;
+}
+/**
+ * Service du data plane admin — vit dans `@nodefony/framework` car lui seul a
+ * le Router pour créer des routes dynamiquement.
+ *
+ * Rôle : collecter les {@link IAdminApi} produits par les modules (et par le
+ * kernel, que framework wrappe), puis monter `/nodefony/<namespace>/api/*` au
+ * boot. À l'exécution, pour chaque requête, le broker :
+ *   1. adapte le `ContextType` HTTP/WS en `IAdminRequest` (params/query/body/
+ *      user/roles/requestId) ;
+ *   2. applique le RBAC (compare `endpoint.role` à `request.roles`, 403 sinon) ;
+ *   3. appelle le `handler`, normalise le retour en `IAdminResponse` ;
+ *   4. sérialise en JSON et pose `content-type: application/json` + status.
+ *
+ * @remarks
+ * Pattern d'enregistrement = **push** : un module appelle `register()` dans son
+ * `onKernelBoot` (cohérent avec `frontendService.registerEntry`). Le kernel ne
+ * pouvant pas importer framework, c'est framework qui construit et enregistre
+ * l'`IAdminApi` du kernel (lecture de `kernel.modules`, `process`, uptime…).
+ *
+ * @remarks
+ * Convention de routage figée (cf CLAUDE.md Studio) : data plane toujours en
+ * **≥ 3 segments** `/nodefony/<module>/api/*` — jamais une route admin
+ * mono-segment `/nodefony/<module>` (collision avec le fallback SPA Studio).
+ *
+ * Étend {@link IAdminRegistry} (core) : un producteur s'enregistre via la vue
+ * minimale `IAdminRegistry` sans dépendre de framework. Ce contrat ajoute le
+ * montage des routes et la résolution — réservés à framework (seul à avoir le
+ * Router). `getApi`/`register`/etc. portent un nom non-`get` pour ne pas masquer
+ * `Service.get` dans l'implémentation (`AdminBroker extends Service`).
+ */
+export interface IAdminBroker extends IAdminRegistry {
+    /** Préfixe racine réservé au framework. Toujours `"/nodefony"`. */
+    readonly rootPrefix: string;
+    /** Segment marqueur du data plane. Toujours `"api"`. */
+    readonly apiSegment: string;
+    /** Rôle exigé par défaut quand un endpoint n'en précise pas. */
+    readonly defaultRole: string;
+    /**
+     * Monte toutes les routes de tous les producteurs enregistrés via le Router
+     * (`Router.createRoute`). Appelé une fois après le boot des modules, quand
+     * tous les `register()` ont eu lieu. Idempotent (no-op si déjà monté).
+     */
+    mountAll(): void;
+    /**
+     * Calcule le chemin absolu d'un endpoint sans le monter.
+     * `("http", "sessions")` → `"/nodefony/http/api/sessions"`.
+     */
+    resolvePath(namespace: string, endpointPath: string): string;
+    /**
+     * Résout une route admin par son nom framework — lookup O(1) utilisé par le
+     * controller pont (`AdminApiController.dispatch`) à chaque requête.
+     */
+    resolve(routeName: string): IAdminRoute | undefined;
+    /**
+     * Introspection : toutes les routes admin résolues (montées ou montables).
+     * Source de l'auto-doc Studio et des tests de non-collision.
+     */
+    routes(): readonly IAdminRoute[];
+}

package/dist/types/nodefony/interfaces/IController.d.ts

@@ -0,0 +1,38 @@
+import type { contextRequest, HTTPMethod, HttpResponse, Http2Response, WebsocketResponse, Session, ContextType } from "@nodefony/http";
+import type { Module, FileClass } from "nodefony";
+import type { OutgoingHttpHeaders } from "node:http";
+import type { ReadStream } from "node:fs";
+import type { IRoute } from "./IRoute.js";
+export interface IController {
+    readonly route?: IRoute | null;
+    request: contextRequest;
+    response: HttpResponse | Http2Response | WebsocketResponse | null;
+    context?: ContextType;
+    session?: Session | null;
+    method?: HTTPMethod;
+    queryGet: Record<string, unknown>;
+    query: Record<string, unknown>;
+    queryFile: unknown[];
+    queryPost: Record<string, unknown>;
+    module?: Module;
+    setContext(context: ContextType): void;
+    setContextJson(encoding?: BufferEncoding): unknown;
+    setContextHtml(encoding?: BufferEncoding): unknown;
+    render(data: unknown, encoding?: BufferEncoding, status?: string | number, headers?: Record<string, string | number>): Promise<unknown>;
+    renderResponse(data: unknown, encoding?: BufferEncoding, status?: string | number, headers?: OutgoingHttpHeaders): Promise<HttpResponse | Http2Response | WebsocketResponse>;
+    renderView(path: string, param?: Record<string, unknown>, status?: string | number, headers?: Record<string, string | number>): Promise<HttpResponse | Http2Response | WebsocketResponse>;
+    renderJson(obj: unknown, status?: string | number, headers?: OutgoingHttpHeaders): Promise<unknown>;
+    setRoute(route: IRoute): IRoute;
+    getSession(): Session | undefined | null;
+    redirect(url: string, status?: string | number, headers?: Record<string, string | number>): void;
+    getFlashBag(key: string): unknown;
+    setFlashBag(key: string, value: unknown): unknown;
+    addFlash(key: string, value: unknown): unknown;
+    forward(name: string, param?: unknown): unknown;
+    /** @deprecated Bloque l'event-loop (`lstatSync`). Préférer `getFileAsync`. */
+    getFile(file: FileClass | string): FileClass;
+    /** Variante async de `getFile` (stat non bloquant via `FileClass.from`). */
+    getFileAsync(file: FileClass | string): Promise<FileClass>;
+    renderFileDownload(file: unknown, options?: unknown, headers?: OutgoingHttpHeaders): Promise<ReadStream>;
+    streamFile(file: FileClass | string, headers?: OutgoingHttpHeaders, options?: Record<string, unknown>): Promise<ReadStream>;
+}

package/dist/types/nodefony/interfaces/IIdempotencyStore.d.ts

@@ -0,0 +1 @@
+export type { IIdempotencyStore, IIdempotencyKeyEntry, IIdempotencyListQuery, IdempotencyOutcome, IdempotentResponse, } from "nodefony";

package/dist/types/nodefony/interfaces/IResolver.d.ts

@@ -0,0 +1,25 @@
+import type { ContextType, HttpError } from "@nodefony/http";
+import type { Injector } from "nodefony";
+import type { ControllerConstructor } from "../src/Route.js";
+import type { IRoute } from "./IRoute.js";
+import type { IController } from "./IController.js";
+export interface IResolver {
+    injector?: Injector | null;
+    controller: ControllerConstructor | null;
+    actionName?: string;
+    action?: (...args: unknown[]) => unknown;
+    context: ContextType;
+    readonly route: IRoute | null;
+    resolve: boolean;
+    variables: unknown[];
+    exception?: HttpError | Error | null;
+    acceptedProtocol: string | null;
+    bypassFirewall: boolean;
+    match(route: IRoute, context: ContextType, cleanPath?: string): unknown;
+    getMatchedParams(): Record<string, unknown>;
+    parsePathernController(name: string): void;
+    getAction(name: string): ((...args: unknown[]) => unknown) | null;
+    newController(context?: ContextType): Promise<IController | object>;
+    callController(data?: unknown[], reload?: boolean): Promise<unknown>;
+    returnController(result: unknown): Promise<unknown>;
+}

package/dist/types/nodefony/interfaces/IRoute.d.ts

@@ -0,0 +1,31 @@
+import type { HTTPMethod, SchemeType, ContextType } from "@nodefony/http";
+import type { ControllerConstructor, RouteRequirements } from "../src/Route.js";
+export interface IRoute {
+    name: string;
+    path?: string;
+    controller?: ControllerConstructor;
+    classMethod?: string;
+    prefix?: string;
+    method?: HTTPMethod;
+    schemes?: SchemeType;
+    pattern?: RegExp;
+    variables: unknown[];
+    defaults: Partial<Record<string, unknown>>;
+    requirements: Partial<RouteRequirements>;
+    hash?: string;
+    host?: string | string[];
+    hostRegexp?: RegExp[];
+    bypassFirewall: boolean;
+    filePath?: string;
+    match(context: ContextType, cleanPath?: string): unknown[] | null | undefined;
+    compile(): RegExp;
+    toString(): string;
+    toObject(): object;
+    setPrefix(prefix?: string): void;
+    setPattern(pattern?: string): string;
+    generateId(): string;
+    addRequirement<K extends keyof RouteRequirements>(key: K, value: RouteRequirements[K]): RouteRequirements[K] | undefined;
+    getRequirement<K extends keyof RouteRequirements>(key: K): RouteRequirements[K] | undefined;
+    hasRequirements(): number;
+    matchRequirements(context: ContextType): boolean;
+}

package/dist/types/nodefony/interfaces/index.d.ts

@@ -0,0 +1,5 @@
+export type { IController } from "./IController.js";
+export type { IRoute } from "./IRoute.js";
+export type { IResolver } from "./IResolver.js";
+export type { IAdminBroker, IAdminRoute } from "./IAdminBroker.js";
+export type { IIdempotencyStore, IdempotencyOutcome, IdempotentResponse, } from "./IIdempotencyStore.js";

package/dist/types/nodefony/service/AdminBroker.d.ts

@@ -0,0 +1,37 @@
+import { Service, Module } from "nodefony";
+import type { IAdminApi } from "nodefony";
+import type { IAdminBroker, IAdminRoute } from "../interfaces/IAdminBroker.js";
+/**
+ * Implémentation du data plane admin (Studio) — collecte les {@link IAdminApi}
+ * et monte `/nodefony/<namespace>/api/*` via le Router.
+ *
+ * Vit dans `@nodefony/framework` : seul niveau qui possède le Router. Le
+ * contrat producteur (`IAdminApi`) vit dans le core (inversion de dépendance).
+ *
+ * @see IAdminBroker pour le contrat public + la convention de routage.
+ */
+declare class AdminBroker extends Service implements IAdminBroker {
+    readonly rootPrefix = "/nodefony";
+    readonly apiSegment = "api";
+    readonly defaultRole = "ROLE_NODEFONY_ADMIN";
+    /** Producteurs enregistrés, indexés par namespace. */
+    private producers;
+    /** Routes résolues, indexées par nom de route (dispatch O(1)). */
+    private byRouteName;
+    /** Module framework propriétaire — requis pour `Router.setController`. */
+    private frameworkModule;
+    /** Vrai une fois `mountAll()` exécuté (idempotence + verrou de register). */
+    private mounted;
+    constructor(module: Module);
+    register(api: IAdminApi): this;
+    unregister(namespace: string): boolean;
+    has(namespace: string): boolean;
+    getApi(namespace: string): IAdminApi | undefined;
+    list(): readonly IAdminApi[];
+    resolvePath(namespace: string, endpointPath: string): string;
+    resolve(routeName: string): IAdminRoute | undefined;
+    routes(): readonly IAdminRoute[];
+    mountAll(): void;
+    private getRouter;
+}
+export default AdminBroker;

package/dist/types/nodefony/service/Eta.d.ts

@@ -0,0 +1,25 @@
+import { Module } from "nodefony";
+import { Eta as EtaEngine } from "eta";
+import Template from "../src/Template.js";
+declare class Eta extends Template {
+    engine: EtaEngine;
+    constructor(module: Module);
+    /**
+     * Rend un template depuis une chaîne source (chemin chaud du Controller).
+     *
+     * @param str - source du template Eta
+     * @param data - locals injectés dans le template
+     * @returns le rendu HTML/texte
+     */
+    render(str: string, data?: Record<string, unknown>): Promise<string>;
+    /**
+     * Rend un template depuis un chemin de fichier (lecture async non bloquante).
+     *
+     * @param path - chemin absolu du fichier `.eta`
+     * @param data - locals injectés dans le template
+     * @returns le rendu HTML/texte
+     * @throws Si la lecture ou le parsing échoue (loggé en ERROR).
+     */
+    renderFile(path: string, data?: Record<string, unknown>): Promise<string>;
+}
+export default Eta;

package/dist/types/nodefony/service/IdempotencyStore.d.ts

@@ -0,0 +1,45 @@
+import { Service, Module } from "nodefony";
+import type { IPage } from "nodefony";
+import type { IIdempotencyKeyEntry, IIdempotencyListQuery, IIdempotencyStore, IdempotencyOutcome, IdempotentResponse } from "../interfaces/IIdempotencyStore.js";
+/**
+ * Implémentation **mémoire** (per-pod) de {@link IIdempotencyStore} — cache borné
+ * de dédup des mutations admin rejouées.
+ *
+ * Vit dans `@nodefony/framework` (niveau qui possède le data plane admin) et
+ * s'enregistre comme service DI `idempotencyStore` (manifeste `@services`).
+ *
+ * **Perf/mémoire** : `Map` allouée **lazy** au 1ᵉʳ `begin` (le store ne sert que
+ * les mutations admin = cold path) ; aucun timer/listener (purge passive +
+ * éviction FIFO au cap, payées seulement quand on écrit). Aucun coût tant
+ * qu'aucune mutation idempotente n'est invoquée.
+ *
+ * @see IIdempotencyStore pour le contrat + l'invariant de scope de la clé.
+ */
+declare class MemoryIdempotencyStore extends Service implements IIdempotencyStore {
+    /** Entrées vivantes — `null` tant qu'aucun `begin` n'a eu lieu (lazy alloc). */
+    private entries;
+    private readonly ttlMs;
+    private readonly leaseMs;
+    private readonly cap;
+    constructor(module: Module);
+    get size(): number;
+    /**
+     * {@inheritDoc IIdempotencyStore.listPage}
+     *
+     * La collection est déjà en RAM et **bornée par le cap** : le tri porte sur
+     * des références, seule la page devient des vues. Les entrées expirées sont
+     * exclues à la LECTURE (la purge d'ici est passive : elle n'a lieu qu'à
+     * l'écriture) — sinon on montrerait comme vivante une clé déjà rejouable.
+     */
+    listPage(query: IIdempotencyListQuery): Promise<IPage<IIdempotencyKeyEntry>>;
+    begin(key: string, fingerprint: string): IdempotencyOutcome;
+    complete(key: string, response: IdempotentResponse): void;
+    abort(key: string): void;
+    /**
+     * Borne la taille : purge passive des expirées rencontrées, puis éviction FIFO
+     * (la plus ancienne insérée) jusqu'à repasser sous le cap. Appelé au `complete`
+     * (seul point qui fait croître durablement la Map).
+     */
+    private evictIfNeeded;
+}
+export default MemoryIdempotencyStore;

package/dist/types/nodefony/service/router.d.ts

@@ -0,0 +1,53 @@
+import { Service, Module } from "nodefony";
+import Route, { RouteOptions } from "../src/Route.js";
+import { ContextType } from "@nodefony/http";
+import Resolver from "../src/Resolver.js";
+import Controller from "../src/Controller.js";
+export type TypeController<T> = new (...args: any[]) => T;
+declare class Router extends Service {
+    static routes: Route[];
+    routes: Route[];
+    private singletonControllers;
+    constructor(module: Module);
+    /**
+     * Retourne l'instance singleton d'une classe controller `@Scope("singleton")`,
+     * en la créant au premier appel via `create`. On cache la **promesse** (pas
+     * l'instance) : N requêtes concurrentes pendant la création (`initialize()`
+     * async) attendent le MÊME travail — jamais deux instances (race de création
+     * éliminée structurellement).
+     *
+     * @param ctor - la classe controller (clé du cache).
+     * @param create - fabrique exécutée une seule fois (instantiate + initialize).
+     * @returns la promesse de l'instance partagée.
+     */
+    getSingletonController(ctor: TypeController<Controller>, create: () => Promise<Controller>): Promise<Controller>;
+    /**
+     * Résout une route pour un contexte donné.
+     *
+     * @param context - le contexte HTTP/WS courant (porte container, méthode, URL…).
+     * @param cleanPathOverride - quand fourni, le matching se fait sur CE pathname au
+     *   lieu de `context.request.url` — permet de router un path **porté par un message**
+     *   (WS-RPC `invoke`) vers une action, sans muter l'URL de la connexion (état partagé).
+     *   `undefined` (cas hot path normal) → comportement inchangé.
+     * @param methodOverride - méthode HTTP **logique** à exiger en plus du transport
+     *   WEBSOCKET (pont WS-RPC `api.request` d'une MUTATION) : lève l'ambiguïté
+     *   GET-via-WS / POST-via-WS sur un même chemin (`context.method` = "WEBSOCKET").
+     *   `undefined` (GET/HTTP) → match historique sur `context.method`.
+     * @returns un `Resolver` (`.resolve === true` si une route a matché).
+     */
+    resolve(context: ContextType, cleanPathOverride?: string, methodOverride?: string): Resolver;
+    resolveController(contex: ContextType, name: string): Resolver;
+    matchRoutes(path: string): RegExpExecArray[];
+    getRoutes(name: string): Route[] | Route | undefined;
+    setRoute(): void;
+    removeRoutes(name: string): void;
+    static createRoute(name: string, obj: RouteOptions): Route;
+    static setController(myconstructor: TypeController<Controller>, module: Module): TypeController<Controller>;
+    /**
+     * Retourne les routes enregistrées pour un controller donné — utilisé par
+     * le décorateur `@controllers` pour logger chaque route depuis le module
+     * propriétaire (msgid `MODULE <name>` au lieu de `KERNEL`).
+     */
+    static getRoutesForController(myconstructor: TypeController<Controller>): Route[];
+}
+export default Router;

package/dist/types/nodefony/src/Controller.d.ts

@@ -0,0 +1,193 @@
+import { Service, Module, FileClass } from "nodefony";
+import type { IController } from "../interfaces/index.js";
+import Route from "./Route.js";
+import { contextRequest, HTTPMethod, HttpResponse, Session, ContextType, Http2Response, WebsocketResponse } from "@nodefony/http";
+import { OutgoingHttpHeaders } from "node:http";
+import { ReadStream } from "node:fs";
+import Eta from "../service/Eta.js";
+type ReadStreamOptions = {
+    flags?: string;
+    encoding?: BufferEncoding;
+    fd?: number;
+    mode?: number;
+    autoClose?: boolean;
+    emitClose?: boolean;
+    start?: number;
+    end?: number;
+    highWaterMark?: number;
+};
+/**
+ * Parse un header `Range` mono-plage en octets (RFC 9110 §14.1.2).
+ *
+ * @param range - valeur brute du header `Range` (ex. `bytes=0-499`, `bytes=-500`).
+ * @param length - taille de la représentation sélectionnée (octets).
+ * @returns bornes `{ start, end }` clampées à la représentation,
+ *   `"unsatisfiable"` si la plage est valide mais hors représentation (→ 416,
+ *   RFC 9110 §15.5.17), ou `null` si le header doit être ignoré — unité ≠
+ *   `bytes`, multi-range non supporté ou syntaxe invalide (RFC 9110 §14.2 :
+ *   un serveur PEUT ignorer un Range ; on répond alors 200 complet, jamais 500).
+ */
+export declare function parseByteRange(range: string, length: number): {
+    start: number;
+    end: number;
+} | "unsatisfiable" | null;
+/**
+ * Scope d'instanciation d'un controller (V4.3).
+ *
+ * - `"request"` (défaut) : une instance par requête — l'état per-request peut
+ *   vivre sur `this` (legacy sûr, zéro breaking).
+ * - `"singleton"` (opt-in via `@Scope`) : UNE instance partagée par toutes les
+ *   requêtes — réservé aux controllers **stateless** (état uniquement via
+ *   arguments décorés + ALS). Un champ mutable par requête sur `this` y serait
+ *   une data race silencieuse entre requêtes concurrentes.
+ */
+export type ControllerScope = "request" | "singleton";
+declare class Controller extends Service implements IController {
+    #private;
+    static prefix: string;
+    /**
+     * Scope d'instanciation de la classe — `"request"` par défaut, `"singleton"`
+     * posé par le décorateur `@Scope` (statique hérité, lu via `new.target` au
+     * constructor et par le Resolver : 0 Reflect). Cf {@link ControllerScope}.
+     */
+    static scope: ControllerScope;
+    module?: Module;
+    template?: Eta | null;
+    /**
+     * Contexte transport courant. Per-request : champ posé par `setContext`
+     * (constructor) — coût d'accès inchangé. Singleton stateless (V4.3) : champ
+     * jamais posé → lecture de l'ALS `RequestContext` (le `HttpKernel` y place
+     * le contexte à l'entrée du scope, V4.1) — chaque appel de helper retrouve
+     * LA requête en cours, jamais celle d'une requête concurrente.
+     */
+    get context(): ContextType | undefined;
+    set context(context: ContextType | undefined);
+    /**
+     * Route matchée. Per-request : posée par le Resolver via `setRoute`.
+     * Sans champ (singleton) : dérive du Resolver de la requête courante
+     * (`context.resolver`), donc toujours la route de CETTE requête.
+     */
+    get route(): Route | null;
+    get request(): contextRequest;
+    set request(request: contextRequest);
+    get response(): HttpResponse | Http2Response | WebsocketResponse | null;
+    set response(response: HttpResponse | Http2Response | WebsocketResponse | null);
+    get method(): HTTPMethod | undefined;
+    set method(method: HTTPMethod | undefined);
+    get queryGet(): Record<string, unknown>;
+    set queryGet(value: Record<string, unknown>);
+    get query(): Record<string, unknown>;
+    set query(value: Record<string, unknown>);
+    get queryFile(): unknown[];
+    set queryFile(value: unknown[]);
+    get queryPost(): Record<string, unknown>;
+    set queryPost(value: Record<string, unknown>);
+    /**
+     * Le CORPS de la requête, parsé — nom universel de l'écosystème (Express,
+     * Fastify, NestJS), alias de {@link queryPost}.
+     *
+     * Ne pas confondre avec {@link query}, qui FUSIONNE la query string et le
+     * corps. Pour une action typée, préférer le décorateur `@Body()`.
+     *
+     * Getter (aucune allocation) : `queryPost` reste la source unique.
+     */
+    get body(): Record<string, unknown>;
+    set body(value: Record<string, unknown>);
+    /**
+     * Session courante, ou `null`. Getter direct sur `context.session` (peuplé au
+     * point d'activation unique du pipeline si la route déclare `@UseSession` /
+     * `@Session`, ou si un cookie de session est repris — L1). Remplace l'ancien
+     * pont via l'event `onSessionStart` : toujours à jour, zéro allocation.
+     */
+    get session(): Session | null;
+    constructor(name: string, context: ContextType);
+    setContext(context: ContextType): void;
+    setContextJson(encoding?: BufferEncoding): void | undefined;
+    setContextHtml(encoding?: BufferEncoding): void | undefined;
+    render(data: unknown, encoding?: BufferEncoding, status?: string | number, headers?: Record<string, string | number>): Promise<Http2Response | HttpResponse>;
+    renderResponse(data: unknown, encoding?: BufferEncoding, status?: string | number, headers?: OutgoingHttpHeaders): Promise<Http2Response | HttpResponse> | Promise<WebsocketResponse>;
+    renderView(path: string | FileClass, param?: Record<string, unknown>, status?: string | number, headers?: Record<string, string | number>): Promise<Http2Response | HttpResponse | WebsocketResponse>;
+    /**
+     * Injecte les helpers frontend (`frontendTags`/`frontendDocument`) dans les
+     * locals du template (passés en data, pas de registre global de fonctions).
+     * Service `frontend` résolu par nom (pas d'import `@nodefony/frontend`). Les
+     * valeurs fournies par l'action priment (spread `param` en dernier).
+     */
+    private withFrontendLocals;
+    renderJson(obj: unknown, status?: string | number, headers?: OutgoingHttpHeaders): Promise<Http2Response | HttpResponse | WebsocketResponse>;
+    setRoute(route: Route): Route;
+    getSession(): Session | undefined | null;
+    redirect(url: string, status?: string | number, headers?: Record<string, string | number>): void;
+    getFlashBag(key: string): unknown;
+    setFlashBag(key: string, value: unknown): unknown;
+    addFlash(key: string, value: unknown): unknown;
+    forward(name: string, param?: unknown[]): Promise<unknown>;
+    /**
+     * @deprecated Bloque l'event-loop (`fs.lstatSync` via `new FileClass`).
+     *   Utiliser {@link getFileAsync} dans tout pipeline. Conservé pour compat.
+     */
+    getFile(file: FileClass | string): FileClass;
+    /**
+     * Variante **async** de `getFile()` — résout les stats via `FileClass.from`
+     * (pas de `lstatSync` bloquant). À préférer dans le pipeline (render/stream).
+     *
+     * Un chemin qui ne désigne aucun fichier rend **404**, pas 500 : la RFC 9110
+     * §15.5.5 définit le 404 comme l'absence de « représentation courante pour la
+     * ressource cible », alors que le 500 (§15.6.1) suppose une condition
+     * **inattendue**. Or le chemin vient presque toujours d'un paramètre d'URL :
+     * un nom qui ne correspond à rien est une entrée client banale, pas une panne.
+     * Un dossier reçoit le même traitement — il n'est pas servable comme fichier.
+     *
+     * Les autres échecs d'accès (permissions, E/S) remontent INCHANGÉS et valent
+     * 500 : là, la condition est bien inattendue. Le 403 ne conviendrait pas, la
+     * RFC le réservant à un refus « compris et délibéré » (§15.5.4).
+     *
+     * Le message rendu au client ne cite JAMAIS le chemin — la même section
+     * autorise le serveur à ne pas divulguer l'existence d'une ressource, et un
+     * chemin serveur dans un corps d'erreur est une fuite d'information. Le chemin
+     * va dans le journal, à la disposition de qui exploite l'application.
+     *
+     * @param file - `FileClass` déjà hydraté OU chemin string.
+     * @returns le `FileClass` (type `"File"` validé).
+     * @throws {HttpError} 404 si le chemin ne désigne aucun fichier.
+     * @throws Si le type de l'argument est invalide (bug d'appel, pas d'entrée client).
+     */
+    getFileAsync(file: FileClass | string): Promise<FileClass>;
+    /**
+     * Sert un fichier en TÉLÉCHARGEMENT (`Content-Disposition: attachment`).
+     *
+     * Comme {@link Controller.streamFile} dont il est l'habillage, il envoie le
+     * fichier ENTIER et n'honore pas `Range` — c'est le comportement voulu pour un
+     * téléchargement. Pour un média seekable, voir {@link Controller.renderMediaStream}.
+     *
+     * @param file - chemin ou `FileClass` du fichier à servir.
+     * @param options - options de `createReadStream`.
+     * @param headers - en-têtes ajoutés (écrasent ceux posés par défaut).
+     * @returns le flux de lecture, une fois la réponse écoulée.
+     */
+    renderFileDownload(file: FileClass | string, options?: ReadStreamOptions, headers?: OutgoingHttpHeaders): Promise<ReadStream>;
+    /**
+     * Envoie un fichier en FLUX, du disque vers la réponse, sans jamais le charger
+     * en mémoire.
+     *
+     * ⚠️ **N'honore PAS l'en-tête `Range`** : le fichier part toujours en entier,
+     * avec un statut 200. Pour un média dans lequel un lecteur doit pouvoir sauter
+     * (vidéo, audio, gros PDF), utiliser {@link Controller.renderMediaStream} —
+     * seul à implémenter les requêtes par plage (RFC 9110 §14 : 206, 416,
+     * `Content-Range`). Annoncer `Accept-Ranges: bytes` depuis ici est un piège :
+     * le client croit pouvoir se déplacer et reçoit tout le fichier.
+     *
+     * Ce que cette méthode garantit et qui justifie son existence : le NETTOYAGE.
+     * Le flux est ouvert en `autoClose: false` ; un client qui raccroche en plein
+     * téléchargement laisserait sinon un descripteur ouvert et une promesse pendue.
+     *
+     * @param file - chemin ou `FileClass` du fichier à servir.
+     * @param headers - en-têtes ajoutés à la réponse (le type MIME est déduit si absent).
+     * @param options - options de `createReadStream` (`start`/`end` pour un extrait).
+     * @returns le flux de lecture, une fois la réponse écoulée.
+     * @throws Si la réponse n'est pas disponible, ou si le fichier est illisible.
+     */
+    streamFile(file: FileClass | string, headers?: OutgoingHttpHeaders, options?: ReadStreamOptions | undefined): Promise<ReadStream>;
+    renderMediaStream(file: FileClass | string, headers?: OutgoingHttpHeaders, options?: ReadStreamOptions | undefined): Promise<HttpResponse | ReadStream | WebsocketResponse>;
+}
+export default Controller;

package/dist/types/nodefony/src/FrameworkAdminApi.d.ts

@@ -0,0 +1,35 @@
+import type { IAdminApi } from "nodefony";
+import type { IAdminBroker } from "../interfaces/IAdminBroker.js";
+/** Options de composition du producteur framework. */
+export interface FrameworkAdminApiOptions {
+    /**
+     * Monte les endpoints Playground (`playground/routes`) — **dev uniquement** :
+     * la console Studio exécute des mutations depuis le navigateur. Hors dev les
+     * endpoints n'existent pas (404) → la page Studio affiche « dev uniquement ».
+     */
+    playground?: boolean;
+}
+/**
+ * Producteur `IAdminApi` du module **framework** — exposé sous
+ * `/nodefony/framework/api/*`.
+ *
+ * 3ᵉ producteur du data plane admin (kernel, http, puis framework). Introspecte
+ * le **Router** : c'est l'équivalent web de `nodefony router:dump` et la source
+ * de la future vue « Routes » de Studio (P10.8).
+ *
+ * Le framework héberge le broker → il s'enregistre directement (pas besoin de
+ * passer par `IAdminRegistry` du container comme un module externe).
+ *
+ * Endpoints :
+ *  - `GET /nodefony/framework/api/routes` → toutes les routes enregistrées
+ *  - `GET /nodefony/framework/api/info`   → résumé (nb routes, méthodes, modules)
+ *  - `GET /nodefony/framework/api/admin`  → **catalogue** du data plane admin
+ *    (tous les producteurs + descriptors + endpoints) — pièce « discovery »
+ *    de P10.2 que Studio lit pour générer sa navigation admin.
+ *
+ * @param broker - le broker admin (pour le catalogue). Optionnel : sans lui,
+ *   `admin` renvoie une liste vide.
+ * @param opts - composition (`playground: true` → endpoints Playground, dev-only).
+ * @returns le contrat admin de framework, prêt à `broker.register()`.
+ */
+export declare function createFrameworkAdminApi(broker?: IAdminBroker, opts?: FrameworkAdminApiOptions): IAdminApi;

package/dist/types/nodefony/src/KernelAdminApi.d.ts

@@ -0,0 +1,71 @@
+import type { IKernel, IAdminApi } from "nodefony";
+/**
+ * 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.
+ */
+export declare function safeConfig(value: unknown, depth?: number, seen?: WeakSet<object>): unknown;
+/** Entrée config d'un module : valeurs redactées + schéma + provenance par champ. */
+export interface IConfigEntry {
+    /** Clé Studio (basename : `http`, `security`, `core`, ou la clé de l'app). */
+    key: string;
+    /** Nom de package (`@nodefony/http`, nom de l'app…). */
+    name: string;
+    /** Est-ce la config de l'APPLICATION (vs un module) ? */
+    isApp: boolean;
+    /** Segment d'adressage des overrides (`NF__<SEG>__…`) : `app` ou le basename. */
+    seg: string;
+    /** Config effective résolue, secrets REDACTÉS côté serveur. */
+    config: Record<string, unknown>;
+    /** JSON Schema du module (si migré Zod), sinon `null`. */
+    configSchema: unknown;
+    /** Origine par champ (`default`/`app`/`env`) — `null` si pas de schéma. */
+    provenance: Record<string, string> | null;
+    /**
+     * « QUI surcharge, où » par champ env-surchargé : chemin pointé → **nom RÉEL**
+     * de la variable d'environnement actuellement posée (`NF__SECURITY__JWT__ACCESSTTLS`).
+     * Permet à Studio de nommer la source exacte (≠ recette générique).
+     */
+    envKeys: Record<string, string>;
+    /**
+     * « QUI surcharge, où » par champ **app**-surchargé : chemin pointé → SOURCE
+     * réelle. Soit un MODULE qui reconfigure celui-ci via `module-<seg>` (cross-module,
+     * ex. `@nodefony/test` qui surcharge `http.upload.maxFileSize`), soit
+     * `nodefony.config.ts` (config app directe / `use()`). Rempli par
+     * {@link attributeOverrideSources} (a besoin de TOUS les modules → côté agrégat).
+     */
+    overriddenBy: Record<string, string>;
+}
+/**
+ * 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.
+ */
+export declare function nodefonyPackageCandidates(name: string): string[];
+export declare function createKernelAdminApi(kernel: IKernel): IAdminApi;