@nodefony/framework 10.0.0-alpha.9 → 10.0.0-beta.2

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

@@ -4,6 +4,8 @@ import type { RouteActionMeta } from "../decorators/routerDecorators.js";
 import Controller from "./Controller.js";
 export interface ControllerConstructor {
     new (...args: any[]): Controller;
+    /** Prototype de la classe — porte les métadonnées des actions (`@Param`…). */
+    readonly prototype: Controller;
 }
 /**
  * Options pour la configuration d'une route.
@@ -62,21 +64,21 @@ export interface RouteOptions {
     areaRoleExempt?: boolean;
 }
 export interface RouteRequirements {
-    domain?: string | string[];
-    scheme?: SchemeType;
-    methods?: HTTPMethod[] | HTTPMethod;
-    protocol?: string;
+    domain?: string | string[] | undefined;
+    scheme?: SchemeType | undefined;
+    methods?: HTTPMethod[] | HTTPMethod | undefined;
+    protocol?: string | undefined;
 }
 declare class Route implements IRoute {
     #private;
     name: string;
-    path?: string;
-    controller?: ControllerConstructor;
-    classMethod?: string;
-    prefix?: string;
-    method?: HTTPMethod;
-    schemes?: SchemeType;
-    pattern?: RegExp;
+    path?: string | undefined;
+    controller?: ControllerConstructor | undefined;
+    classMethod?: string | undefined;
+    prefix?: string | undefined;
+    method?: HTTPMethod | undefined;
+    schemes?: SchemeType | undefined;
+    pattern?: RegExp | undefined;
     variables: string[];
     /**
      * Caractères du chemin déclaré qu'une requête ne peut PAS porter — la route
@@ -85,18 +87,18 @@ declare class Route implements IRoute {
      *
      * @see {@link UNREACHABLE_IN_PATHNAME}
      */
-    unreachableChars?: string[];
+    unreachableChars?: string[] | undefined;
     defaults: Partial<Record<string, unknown>>;
     requirements: Partial<RouteRequirements>;
-    hash?: string;
-    host?: string | string[];
+    hash?: string | undefined;
+    host?: string | string[] | undefined;
     /**
      * Patterns de domaine pré-compilés (host + `requirements.domain`), RegExp
      * ancrées/wildcard. Compilé UNE fois dans {@link compile} ; testé par requête
      * via {@link isDomainAllowed} (zéro alloc hot-path). `undefined` = route servie
      * sur tous les vhosts.
      */
-    hostRegexp?: RegExp[];
+    hostRegexp?: RegExp[] | undefined;
     /**
      * P3a — requirements pré-compilés au boot (0 alloc par match) :
      * `methodsSet` = méthodes autorisées normalisées UPPERCASE (lookup O(1)) ;
@@ -104,9 +106,9 @@ declare class Route implements IRoute {
      * `varRegexp` = requirements de variables de route (string → RegExp).
      * `this.requirements` reste la config BRUTE (hash de route + introspection).
      */
-    methodsSet?: Set<string>;
-    methodsAllow?: string;
-    varRegexp?: Record<string, RegExp>;
+    methodsSet?: Set<string> | undefined;
+    methodsAllow?: string | undefined;
+    varRegexp?: Record<string, RegExp> | undefined;
     bypassFirewall: boolean;
     /**
      * La route décide seule de son autorisation → la zone du firewall n'applique
@@ -119,7 +121,7 @@ declare class Route implements IRoute {
      * `routeExpectsBodyStream(route)` via lecture `Reflect` des `ParamMeta`, O(1)
      * ensuite). Lu en amont par `handleHttp` pour sauter le parse.
      */
-    bodyStream?: boolean;
+    bodyStream?: boolean | undefined;
     /**
      * P5 — Metadata d'action figées (`@HttpCode`/`@Header`/`@Redirect`/params/
      * session), memo au 1er hit comme {@link bodyStream} : `undefined` = pas
@@ -127,8 +129,8 @@ declare class Route implements IRoute {
      * ensuite → plus aucun `Reflect.getMetadata` par requête). Objet PARTAGÉ
      * entre requêtes — ne jamais muter. Posé après `generateId()` → hash stable.
      */
-    actionMeta?: RouteActionMeta;
-    filePath?: string;
+    actionMeta?: RouteActionMeta | undefined;
+    filePath?: string | undefined;
     /**
      * Module propriétaire de la route — set par `Router.setController()` à
      * `onBoot`, donc PAS disponible à la création de la route (via `@controller`)
@@ -136,7 +138,7 @@ declare class Route implements IRoute {
      */
     module?: {
         name: string;
-    };
+    } | undefined;
     constructor(name: string, obj?: RouteOptions);
     /**
      * Normalise le pathname de la requête pour le matching : retire le(s)
@@ -149,7 +151,21 @@ declare class Route implements IRoute {
      * @returns le pathname sans slash final, ou `undefined` si la requête n'a pas d'URL.
      */
     static cleanPathname(context: ContextType): string | undefined;
-    match(context: ContextType, cleanPath?: string, methodOverride?: string): ((string | null)[] & Record<string, unknown>) | null | undefined;
+    /**
+     * 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: ContextType, cleanPath?: string, methodOverride?: string, literal?: boolean): ((string | null)[] & Record<string, unknown>) | null | undefined;
     /**
      * Compile the route into a regular expression pattern.
      * @returns The compiled regular expression pattern.

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

@@ -1,3 +1,4 @@
+import type { IPackageManagerResolution } from "nodefony";
 /**
  * Frontmatter d'un fichier de doc module. Tous les champs sont optionnels —
  * un `.md` sans frontmatter reste lisible (titre dérivé du premier `# H1`).
@@ -12,7 +13,7 @@ export interface DocFrontmatter {
     since?: string;
     updated?: string;
     status?: string;
-    order?: number;
+    order?: number | undefined;
     [key: string]: unknown;
 }
 /** Entrée du sommaire docs d'un module (sans le corps markdown). */
@@ -138,7 +139,7 @@ export interface DocSearchResult {
      * est rendu : annoncer une coupe qui n'a pas eu lieu ferait chercher un
      * reste inexistant.
      */
-    note?: string;
+    note?: string | undefined;
 }
 /**
  * Cherche un texte dans les docs colocalisées des modules donnés.
@@ -164,7 +165,7 @@ export interface DocSearchResult {
  * @returns les docs retenues, et ce que la recherche a réellement balayé
  */
 export declare function searchModuleDocs(targets: readonly DocSearchTarget[], query: string, options?: {
-    limit?: number;
+    limit?: number | undefined;
     perDoc?: number;
 }): Promise<DocSearchResult>;
 /**
@@ -297,21 +298,30 @@ export interface TestRunCommand {
  *   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
  */
-export declare function testRunCommand(modulePath: string, file?: string): TestRunCommand;
+export declare function testRunCommand(modulePath: string, file?: string, manager?: IPackageManagerResolution["name"]): TestRunCommand;
 /**
  * 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 `..`).
  */
 export declare function runModuleTests(modulePath: string, file?: string): Promise<TestRunResult>;
 /**

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

@@ -0,0 +1,53 @@
+/**
+ * Filets d'un contrôleur **singleton** — le défaut : UNE instance par classe,
+ * partagée par toutes les requêtes, concurrentes comprises.
+ *
+ * Un singleton ne peut porter aucun état de requête sur `this` : la valeur
+ * écrite par une requête serait lue par la suivante — une fuite de données
+ * entre utilisateurs, sans la moindre erreur. Deux filets la rendent visible :
+ *
+ * - les accesseurs d'état par requête de `Controller` (`query`, `request`,
+ *   `context`…) refusent l'écriture sur un singleton, dans tous les
+ *   environnements (coût nul : ils ne sont jamais écrits sur le chemin chaud) ;
+ * - en développement seulement, {@link guardSingletonState} fait lever toute
+ *   écriture sur un champ de l'instance, une fois sa construction et son
+ *   `initialize()` terminés.
+ *
+ * @module
+ */
+/**
+ * `true` si l'environnement du kernel est celui du développement.
+ *
+ * Une seule définition pour tout le paquet : la sonde CSP de `Controller` et le
+ * filet des singletons s'allument sur le même critère.
+ *
+ * @param environment - `kernel.environment`, tel quel.
+ * @returns `true` en développement (`"development"` ou son alias `"dev"`).
+ */
+export declare function isDevelopment(environment: unknown): boolean;
+/**
+ * Message d'une écriture refusée sur un contrôleur singleton : il nomme la
+ * classe, le membre, la raison du refus et les deux remèdes.
+ *
+ * @param controller - nom de la classe du contrôleur.
+ * @param member - membre écrit (`count`, `query`…).
+ * @returns le message, en une phrase par idée.
+ */
+export declare function singletonWriteMessage(controller: string, member: string): string;
+/**
+ * En développement, fait lever toute écriture sur un champ d'un contrôleur
+ * singleton, avec un message qui nomme le contrôleur, le champ et le remède.
+ *
+ * Chaque propriété PROPRE inscriptible devient un accesseur : la lecture rend
+ * la valeur posée à la construction ou dans `initialize()`, l'écriture lève.
+ * L'instance est ensuite rendue non extensible, pour qu'un champ non déclaré
+ * ne puisse pas être ajouté en cours de requête.
+ *
+ * Ce que le filet n'attrape PAS, et que seule la relecture garde : les champs
+ * `#privés` (ce ne sont pas des propriétés), et les mutations internes d'un
+ * objet tenu par un champ (`this.cache.set(…)`, `this.list.push(…)`).
+ *
+ * @param controller - l'instance, construite et initialisée.
+ * @param name - nom de sa classe, pour le message.
+ */
+export declare function guardSingletonState(controller: object, name: string): void;

package/docs/admin.md

@@ -336,7 +336,7 @@ montée avec `[method, "WEBSOCKET"]`. Elle devient donc invocable par le pont WS
 Les **mutations** sont pontables par socket. La sécurité d'écriture repose alors sur l'**idempotence**
 (`idempotencyGate()`, `AdminApiController.ts:131`) : la clé `Idempotency-Key` est **obligatoire en
 WS** (une socket reconnecte et rejoue), **optionnelle en HTTP** (`required: false`,
-`AdminApiController.ts:184`). Un `GET` n'est jamais idempotenté (`AdminApiController.ts:149`) ; la
+`AdminApiController.ts:149`). Un `GET` n'est jamais idempotenté (`AdminApiController.ts:135`) ; la
 porte est évaluée **après** le RBAC (un 403 ne consomme aucune entrée). Le helper est le **même** que
 le seam `@Idempotent` des controllers userland — voir [Idempotence](idempotence.md).