nodefony 7.0.2 → 10.0.0-alpha.2

package/dist/client/types/src/syslog/drivers/pduFlow.d.ts

@@ -0,0 +1,53 @@
+import type { IPduLike } from "./ILogDriver.js";
+import type { LogProtocol } from "./pduProtocol.js";
+/**
+ * **Étape logique du cycle de vie d'une requête / connexion** — identifiant
+ * STABLE (clé de filtre côté back ET clé de mapping libellé/couleur côté front).
+ *
+ * Les logs DEBUG du pipeline portent des noms d'events bruts (`onRequest`,
+ * `onRequestEnd`, `onSend`…) peu parlants, et dont l'ordre d'apparition n'est pas
+ * l'ordre intuitif (`onRequestEnd` = corps reçu, donc TÔT pour un GET malgré le
+ * mot « End »). Chaque event est ici mappé vers une étape nommée — la base d'un
+ * filtre fiable (≠ recherche texte, qui matchait par erreur les URL contenant le
+ * marqueur) et d'une lecture « je comprends où en est la requête ».
+ */
+export type FlowStepId = "request-in" | "body-received" | "route-matched" | "kernel-dispatch" | "response" | "request-end" | "finish" | "ws-open" | "ws-message" | "ws-close" | "session" | "session-saved";
+/**
+ * Métadonnée **structurelle** d'une étape (jamais de présentation : libellé FR et
+ * couleur vivent côté front, qui mappe l'`id`). `order` = rang logique dans le
+ * cycle de SON protocole ; `protocol` = où l'étape apparaît (`"both"` = session).
+ */
+export interface FlowStepMeta {
+    /** Rang logique dans le cycle (tri du sélecteur d'étapes). */
+    order: number;
+    /** Protocole d'appartenance — pilote le sélecteur adaptatif côté Studio. */
+    protocol: LogProtocol | "both";
+}
+/**
+ * Table des étapes — **source unique** de l'ordre et de l'appartenance protocole,
+ * partagée back (filtre) et front (sélecteur groupé HTTP / WebSocket / Commun).
+ */
+export declare const FLOW_STEPS: Record<FlowStepId, FlowStepMeta>;
+/**
+ * Entrée minimale pour classer une étape — seuls `msgid`, `payload` et `msg`
+ * comptent. Un `Pdu`, un {@link IPduLike} (msg requis) ET un record wire relu
+ * (`ILogRecord` / miroir front, `msg` optionnel) la satisfont structurellement
+ * → la classification est utilisable des deux côtés de la frontière isomorphe.
+ */
+export type FlowClassifiable = Pick<IPduLike, "msgid" | "payload"> & {
+    msg?: string;
+};
+/**
+ * Classe un Pdu en **étape de cycle de vie** (id stable) ou `null` si la ligne
+ * n'est pas un jalon (log applicatif libre, ex. `DB-DEMO`). PUR, isomorphe,
+ * 0 état — réutilisé par le filtre back ({@link filterPdus}) ET le rendu front
+ * (colonne « Étape » + sélecteur) → une SEULE logique, jamais de divergence.
+ *
+ * Priorité aux marqueurs de **contenu** (route, session, cookie, bilan), puis au
+ * **nom d'event** générique. `onRequest` est désambiguïsé par le msgid `KERNEL`
+ * (dispatch kernel) vs contexte (entrée de requête).
+ *
+ * @param pdu - enregistrement (Pdu ou {@link IPduLike}, relu d'un JSONL aussi).
+ * @returns l'`id` d'étape, ou `null` pour un log hors cycle.
+ */
+export declare function pduFlowStep(pdu: FlowClassifiable): FlowStepId | null;

package/dist/client/types/src/syslog/drivers/pduProtocol.d.ts

@@ -0,0 +1,20 @@
+import type { IPduLike } from "./ILogDriver.js";
+/** Protocole d'origine d'un enregistrement de log. */
+export type LogProtocol = "ws" | "http";
+/**
+ * Classe un Pdu par **protocole** d'origine — `"ws"` ou `"http"` — de façon PURE,
+ * isomorphe et 0-alloc (une seule comparaison de `msgid`).
+ *
+ * Critère FIABLE : tout log émis dans un contexte WebSocket porte le msgid
+ * `"WEBSOCKET CONTEXT"` (forcé par défaut dans `WebsocketContext.log()`). Tout le
+ * reste du pipeline (req/http2/router/firewall/kernel/applicatif) est classé HTTP.
+ * Une seule logique → front et back ne divergent plus (le front filtrait par texte,
+ * source de faux positifs).
+ *
+ * Seul `msgid` compte → accepte un `Pdu`, un {@link IPduLike} ou un record wire
+ * relu (`ILogRecord` / miroir front) indifféremment.
+ *
+ * @param pdu - tout objet portant un `msgid`.
+ * @returns `"ws"` si le log provient d'une socket WebSocket, sinon `"http"`.
+ */
+export declare function pduProtocol(pdu: Pick<IPduLike, "msgid">): LogProtocol;

package/dist/client/types/src/syslog/logColor.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Gate de couleur ANSI des logs — résolue **une seule fois au boot**
+ * ({@link Kernel.initializeLog}), pas par log.
+ *
+ * Problème résolu : plusieurs loggers (Kernel, Context, request-logger…) bakent
+ * des codes ANSI DANS le `payload`/`msgid` d'un `Pdu` (ex. `clc.cyan("URL")`).
+ * Ces Pdu voyagent jusqu'au `FileTransport` JSON → l'ANSI polluait le `.jsonl`
+ * queryable (et le pipe stdout → collecteur en prod). Stripper à l'écriture =
+ * un `.replace()` PAR log sur le hot path (refusé, coût). À la place, un flag
+ * global gate la couleur à la SOURCE.
+ *
+ * Critère (résolu au boot) : couleur ON si `stdout` est un **TTY** (un humain
+ * regarde un terminal) ; OFF si pipe/fichier/redirection (prod, collecteur,
+ * conteneur) → payloads bruts → JSONL et stdout propres.
+ *
+ * Perf : les slots ci-dessous sont MUTÉS une fois (`setLogColor`) — le hot path
+ * appelle directement `identity` (OFF) ou la fonction `cli-color` (ON), **sans
+ * test booléen par log**. Reproduire `clc.x.y` ici garde le chaînage hors du
+ * hot path (une fonction figée, pas une chaîne de getters par appel).
+ *
+ * Isomorphe : au navigateur, `cli-color` est remplacé par le shim identité
+ * (alias rollup) → ON ≡ OFF, jamais d'ANSI quoi qu'il arrive.
+ */
+type ColorFn = (s: string | number) => string;
+/** Combinaisons `cli-color` réellement utilisées par les loggers Nodefony. */
+declare const KEYS: readonly ["cyan", "magenta", "red", "green", "yellow", "blue", "blackBright", "yellowBold", "redBold", "cyanBold", "blueBrightBold", "cyanBgBlue", "cyanBgBlack"];
+type ColorKey = (typeof KEYS)[number];
+type ColorMap = Record<ColorKey, ColorFn>;
+/**
+ * Helper de couleur partagé — référence STABLE, propriétés mutées par
+ * {@link setLogColor}. Les call-sites font `logColor.cyan("URL")`.
+ */
+export declare const logColor: ColorMap;
+/**
+ * Active/désactive la couleur ANSI des logs — à appeler **une fois au boot**.
+ * Swap les fonctions des slots ; aucun coût par log ensuite.
+ *
+ * @param enabled - `true` = couleur (TTY interactif), `false` = brut (pipe/fichier).
+ */
+export declare function setLogColor(enabled: boolean): void;
+/** `true` si la couleur ANSI est active (gate boot-time). */
+export declare function isLogColorEnabled(): boolean;
+/**
+ * Applique les conventions d'environnement couleur PAR-DESSUS un signal `isTTY`
+ * **déjà résolu** — au boot on passe `Kernel.isTTY` (qui honore déjà `NF_NO_TTY`),
+ * sans re-lire `process.stdout`. Conventions :
+ *
+ * - **`NO_COLOR`** (no-color.org) : présent **et non vide** → couleur OFF, quelle
+ *   que soit sa valeur. Priorité absolue (refus explicite de l'utilisateur).
+ * - **`FORCE_COLOR`** : non vide et ≠ `"0"` → couleur ON (override pipe/non-TTY,
+ *   ex. CI qui veut des logs colorés capturés).
+ * - sinon → couleur = `isTTY`.
+ *
+ * Isomorphe : `env` lu via `globalThis.process` (navigateur : pas de `process`).
+ *
+ * @param isTTY - signal TTY déjà résolu (ex. `Kernel.isTTY`, NF_NO_TTY-aware).
+ */
+export declare function resolveColorEnabled(isTTY: boolean): boolean;
+export {};

package/dist/client/types/src/types/ICliKernel.d.ts

@@ -0,0 +1,28 @@
+import type { Command as CommanderCommand } from "commander";
+import type { EnvironmentType, DebugType } from "./globals.js";
+type RunLifetime = "oneshot" | "longrunning";
+interface IRunProfile {
+    servers: boolean;
+    lifetime: RunLifetime;
+    interactive: boolean;
+}
+export interface ICliKernel {
+    commander: CommanderCommand | null;
+    environment: EnvironmentType;
+    runProfile: IRunProfile;
+    /** Boot silencieux d'une commande CLI utilitaire (cf CliKernel.quietBoot). */
+    quietBoot?: boolean;
+    debug: DebugType;
+    pid: number | null;
+    setProcessTitle(name?: string): void;
+    showBanner(): void;
+    blankLine(): void;
+    clear(): void;
+    showAsciify(name: string | null): Promise<unknown>;
+    parseCommandAsync(argv?: string[]): Promise<CommanderCommand>;
+    runCommandAsync(cmd: string, args?: string[]): Promise<CommanderCommand>;
+    setPackageManager(manager?: string): unknown;
+    setCommandVersion(version: string): CommanderCommand;
+    initSyslog(env?: EnvironmentType, debug?: DebugType): void | null;
+}
+export {};

package/dist/client/types/src/types/ICommand.d.ts

@@ -0,0 +1,14 @@
+type KernelEventKey = "onInit" | "onPreStart" | "onStart" | "onPreRegister" | "onRegister" | "onPreBoot" | "onBoot" | "onReady" | "onServersReady" | "onPostReady" | "onTerminate";
+type RunLifetime = "oneshot" | "longrunning";
+export type { KernelEventKey, RunLifetime };
+export interface ICommand {
+    name: string;
+    kernelEvent: KernelEventKey;
+    /**
+     * Durée de vie DÉCLARÉE par la commande : `"oneshot"` (build/install/batch → terminate
+     * une fois la phase atteinte) ou `"longrunning"` (daemon CONSOLE → le Kernel parke au
+     * lieu de terminer, cf `Kernel.finishOrPark`). Capability déclarative, lue par le Kernel.
+     */
+    lifetime: RunLifetime;
+    action(...args: unknown[]): Promise<unknown>;
+}

package/dist/client/types/src/types/IContainer.d.ts

@@ -0,0 +1,35 @@
+import type { DynamicParam } from "../Container.js";
+import type { Pci, Severity, Msgid, Message } from "../syslog/Pdu.js";
+import type Syslog from "../syslog/Syslog.js";
+/**
+ * Contrat public d'un scope (Container enfant lié à un parent).
+ * Étend IContainer et ajoute name + getParameters avec merge/deep.
+ */
+export interface IScope extends IContainer {
+    readonly name: string;
+    getParameters(name: string, merge?: boolean, deep?: boolean): DynamicParam | null;
+}
+/**
+ * Contrat public du DI Container nodefony.
+ * Container et Scope l'implémentent.
+ */
+export interface IContainer {
+    readonly id: string;
+    set<T>(name: string, object: T): void;
+    get<T = unknown>(name: string): T | null;
+    remove(name: string): boolean;
+    has(name: string): boolean;
+    keys(): string[];
+    entries(): [string, unknown][];
+    setParameters<T>(name: string, ele: T): DynamicParam | null;
+    getParameters(name: string): DynamicParam | null;
+    addScope(name: string): object;
+    enterScope(name: string): IScope;
+    leaveScope(scope: IScope): void;
+    removeScope(name: string): void;
+    /** Nombre d'instances vivantes du scope nommé (introspection/sondes). */
+    scopeCount(name: string): number;
+    log(pci: Pci, severity?: Severity, msgid?: Msgid, msg?: Message): ReturnType<Syslog["log"]> | void;
+    clean(): void;
+    reset(): void;
+}

package/dist/client/types/src/types/IKernel.d.ts

@@ -0,0 +1,138 @@
+import type { IService } from "./IService.js";
+import type { IModule } from "./IModule.js";
+import type { IBootReport } from "../kernel/bootReport.js";
+import type { IReadinessContributor } from "../kernel/readinessRegistry.js";
+import type FileClass from "../FileClass.js";
+import type { EnvironmentType, DebugType } from "./globals.js";
+import type { ICliKernel } from "./ICliKernel.js";
+import type { IInfra, IStoreResolution } from "../config/infra.js";
+import type { ICommand } from "./ICommand.js";
+import type os from "node:os";
+type RunLifetime = "oneshot" | "longrunning";
+interface IRunProfile {
+    servers: boolean;
+    lifetime: RunLifetime;
+    interactive: boolean;
+}
+type EventsType = Record<string, number>;
+type TrunkType = "javascript" | "typescript" | null;
+export interface KernelNetworkResult {
+    external: Record<string, os.NetworkInterfaceInfo[]>;
+    local: Record<string, os.NetworkInterfaceInfo[]>;
+    ipv4: Record<string, os.NetworkInterfaceInfo[]>;
+    ipv6: Record<string, os.NetworkInterfaceInfo[]>;
+    interfaces: Record<string, os.NetworkInterfaceInfo[]>;
+}
+/**
+ * Contrat public du Kernel nodefony.
+ * Utilisé comme type de IService.kernel pour éviter l'import circulaire
+ * Kernel.ts → Service.ts → IService.ts → IKernel.ts → Kernel.ts.
+ *
+ * IModule sera ajouté quand IModule sera défini (getModule/modules typés object pour l'instant).
+ * command/commandArgs typés object/unknown[] — ICommand session dédiée.
+ */
+export interface IKernel extends IService {
+    runProfile: IRunProfile;
+    readonly version: string;
+    readonly environment: EnvironmentType;
+    readonly debug: DebugType;
+    readonly projectName: string;
+    readonly path: string;
+    /**
+     * Répertoire des données runtime PERSISTÉES (`<path>/var`) — base commune des
+     * stores fichier (passkeys, TOTP, sessions) et bases SQLite. Gitignoré ; garanti
+     * créé au boot (comme `tmpDir`, éphémère). Absent tant que le Kernel n'a pas booté.
+     */
+    readonly varDir?: FileClass;
+    readonly isDev: boolean;
+    readonly isProd: boolean;
+    /**
+     * Infra déclarée (`database`/`cache`/`logs`) résolue depuis l'environnement
+     * (URLs `NF_DATABASE_URL`/`NF_REDIS_URL`/…). Mémoïsée — consommée par les
+     * briques dont le store vaut `"auto"` (`resolveAutoStore`).
+     */
+    readonly infra: IInfra;
+    /**
+     * Résolutions EFFECTIVES des stores de persistance, capturées au boot par
+     * chaque brique (`registerStoreResolution`) — la vérité vécue (replis inclus),
+     * alimente l'écran Studio « Stores ». Vide tant qu'aucune brique n'a résolu.
+     */
+    readonly storeResolutions: IStoreResolution[];
+    /**
+     * Enregistre la résolution effective d'une brique de persistance (idempotent
+     * par `brick` — la dernière résolution gagne). La provenance est dérivée de
+     * `configured` (`"auto"` → `"infra"`, sinon `"explicit"`). Appelé au boot,
+     * après le `log()` de résolution du consommateur.
+     */
+    registerStoreResolution(resolution: Omit<IStoreResolution, "provenance">): void;
+    /**
+     * L'environnement FOURNIT-il un vrai terminal ? Résolu une fois au boot
+     * (`process.stdout.isTTY`, surchargeable `NF_NO_TTY`). Volet « environnement » qui
+     * complète `runProfile.interactive` (besoin déclaré) : un prompt n'a de sens que si
+     * `runProfile.interactive && kernel.isTTY`. Cloud-native (pod/CI) → toujours `false`.
+     */
+    readonly isTTY: boolean;
+    readonly pid: number;
+    readonly platform: NodeJS.Platform;
+    /** Répertoire temporaire du projet (`<cwd>/tmp`), initialisé au boot. */
+    tmpDir?: FileClass;
+    readonly started: boolean;
+    readonly booted: boolean;
+    readonly ready: boolean;
+    readonly postReady: boolean;
+    /** Supprime les bannières serveurs sous l'écran de boot animé (dev). */
+    readonly suppressBootBanners: boolean;
+    readonly Events: Readonly<EventsType>;
+    readonly progress: number;
+    readonly trunk: TrunkType;
+    command: ICommand | null;
+    commandArgs: unknown[];
+    domain: string;
+    cli: ICliKernel | null;
+    readonly modules: Record<string, IModule>;
+    start(): Promise<this>;
+    /** `quiet` muselle l'affichage (log « terminate : N ») — jamais le drain. */
+    terminate(code?: number, quiet?: boolean): Promise<this>;
+    isTrunk(): Promise<TrunkType>;
+    isModule(subclass: unknown): boolean;
+    addModule(Mod: unknown, ...args: unknown[]): Promise<IModule>;
+    loadModule(nameOrPath: string): Promise<IModule>;
+    getModule(name: string): IModule;
+    getModules(): Record<string, IModule>;
+    getNetwork(): KernelNetworkResult;
+    checkPath(myPath: string): string | null;
+    isCommandComplete(progress: number): boolean;
+    /** Verdict agrégé du dernier boot (modules, serveurs, santé) — vérité unique. */
+    getBootReport(): IBootReport;
+    /** AJOUTE une ligne de détail à afficher sous une phase de boot (canal neutre). */
+    reportBootLine(phase: string, line: string): void;
+    /** REMPLACE les lignes de détail d'une phase (producteur idempotent). */
+    setBootLines(phase: string, lines: string[]): void;
+    /** Lignes de détail déclarées pour une phase de boot. */
+    getBootLines(phase: string): string[];
+    /**
+     * Nombre de composants qui retiennent la mise en service — `0` = disponible.
+     * Verdict DÉJÀ calculé : le lire ne déclenche aucune vérification.
+     */
+    readonly readinessBlocked: number;
+    /**
+     * Ce processus a-t-il le droit de recevoir du trafic ?
+     *
+     * La règle de mise en service, en UN point : cycle de démarrage TERMINÉ
+     * (`postReady`) et aucun composant qui retienne. Lue telle quelle par la
+     * sonde `/readyz` et par le champ `ready` du plan d'administration — les
+     * recomposer chacun de son côté les a déjà fait diverger.
+     */
+    readonly servable: boolean;
+    /**
+     * Pose le verdict de disponibilité d'un composant nommé (schéma en retard,
+     * cache froid…). Un seul `false` suffit à faire rendre 503 à `/readyz` ;
+     * `/livez` reste 200 — un état externe ne se répare pas par un redémarrage.
+     */
+    setReadiness(name: string, ready: boolean, reason?: string): void;
+    /** Retire un contributeur : sa voix ne retient plus rien. */
+    clearReadiness(name: string): void;
+    /** État de chaque contributeur — pour un diagnostic, jamais pour la sonde. */
+    readinessReport(): IReadinessContributor[];
+}
+export {};

package/dist/client/types/src/types/IMcpTool.d.ts

@@ -0,0 +1,157 @@
+/**
+ * Contrat d'un outil **Model Context Protocol** — défini dans le CORE.
+ *
+ * Vit ici, et non dans le module qui sert la porte HTTP, pour la raison qui
+ * gouverne déjà {@link IAdminApi} : un outil peut être produit par n'importe
+ * quel niveau de la pile — un module métier d'application, un adapter ORM, un
+ * futur module IA — et le contrat doit donc résider au plus bas niveau commun.
+ * Un contrat logé dans un module `policy: "dev"` obligerait toute application
+ * voulant déclarer un outil à dépendre d'un paquet qui disparaît en production.
+ *
+ * Séparation des rôles :
+ *  - Ce fichier = **producteur**. Un module déclare *quels* outils il offre, par
+ *    `getMcpTools()`, sans rien connaître du transport ni du protocole.
+ *  - `mcp/server.ts` (core) = **protocole**. Il reçoit des outils déjà résolus.
+ *  - Un controller de module = **transport**. Il traduit HTTP ↔ JSON-RPC.
+ */
+/**
+ * Ce que rend un outil — du contenu, et l'aveu d'un échec métier.
+ *
+ * Un échec métier se dit par `isError`, jamais par une exception : le protocole
+ * réserve ses erreurs aux fautes de protocole. La distinction compte pour
+ * l'agent — une erreur de protocole signifie « tu t'y prends mal », un `isError`
+ * signifie « ta demande est recevable, voici pourquoi elle n'aboutit pas » ;
+ * c'est la seconde qu'il peut corriger seul.
+ */
+export interface IMcpToolResult {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    isError?: boolean;
+}
+/**
+ * Ce que le transport a pu ÉTABLIR de l'appelant — jamais ce qu'il prétend.
+ *
+ * La spec autorise le catalogue à varier selon l'autorisation présentée, et
+ * pose la condition qui rend cela sûr : « credentials are **per-request input,
+ * not connection state** ». D'où cet objet, construit à CHAQUE requête par la
+ * porte, et jamais mémorisé entre deux.
+ *
+ * ⚠️ **Une porte qui n'authentifie pas rend un appelant anonyme** — pas une
+ * autorisation implicite. Tant que le rôle *resource server* n'est pas branché,
+ * `authenticated` est `false` et `scopes` est vide : les outils qui exigent
+ * quoi que ce soit sont retenus, jamais servis par défaut.
+ */
+export interface IMcpCaller {
+    /**
+     * Une identité a-t-elle été PROUVÉE (jeton validé) ?
+     *
+     * `false` par défaut, et c'est le seul défaut sûr : le jour où quelqu'un
+     * branche une porte authentifiée en oubliant de poser ce drapeau, les outils
+     * protégés restent invisibles — l'inverse aurait ouvert.
+     */
+    authenticated: boolean;
+    /** Scopes réellement accordés par le serveur d'autorisation. */
+    scopes: readonly string[];
+    /**
+     * Rôles Nodefony de cet appelant — ce sur quoi le plan d'administration
+     * tranche.
+     *
+     * Posés par la PORTE, qui seule connaît sa configuration : une porte non
+     * protégée (module de développement, bornée par son périmètre et ses gardes
+     * de transport) accorde le rôle d'opérateur et l'ÉNONCE ; une porte protégée
+     * les dérive du jeton ({@link rolesFromScopes}) et n'accorde rien d'autre.
+     *
+     * Champ **obligatoire** : le compilateur force chaque porte à décider. Il l'a
+     * été après avoir constaté l'inverse — la lecture d'administration fabriquait
+     * un administrateur, donc tout porteur d'un jeton d'audience valide, même
+     * sans aucun droit, obtenait tout.
+     */
+    roles: readonly string[];
+    /** Sujet du jeton (`sub`), pour l'audit et pour filtrer les données rendues. */
+    subject?: string;
+}
+/** Un outil tel que `tools/list` le publie — sans son implémentation. */
+export interface IMcpToolDefinition {
+    /**
+     * Identifiant d'appel. Forme admise : `[a-zA-Z0-9_-]{1,64}`.
+     *
+     * Ce nom ne reste pas dans le serveur — il voyage jusque dans le contexte du
+     * modèle. Un nom hors forme n'échoue pas franchement : il produit des appels
+     * que rien ne résout.
+     */
+    name: string;
+    /**
+     * ⭐ **Le premier critère de déclenchement de l'outil**, avant toute
+     * considération technique. Un modèle n'appelle pas ce qu'il ne comprend pas :
+     * dire ce que l'outil REND et QUAND s'en servir, pas seulement son nom.
+     */
+    description: string;
+    /** Schéma JSON des arguments attendus. */
+    inputSchema: Record<string, unknown>;
+}
+/**
+ * Un outil exécutable : ce que `tools/list` publie, plus ce qui répond.
+ *
+ * C'est le contrat qu'un module implémente pour ajouter un outil à la porte MCP
+ * de son application. Le handler ne reçoit QUE les arguments de l'agent : tout
+ * ce dont il a besoin par ailleurs (services, kernel, connexions) est capturé
+ * par fermeture au moment de la déclaration — le déclarant est un module, il a
+ * déjà tout sous la main.
+ *
+ * @example
+ * ```ts
+ * import { Module, mcpText, type IMcpTool } from "nodefony";
+ *
+ * class Shop extends Module {
+ *   getMcpTools(): IMcpTool[] {
+ *     return [{
+ *       name: "shop_stock",
+ *       description:
+ *         "Stock réel d'une référence produit. À utiliser avant de proposer " +
+ *         "une commande — la réponse vient de la base, pas d'un cache.",
+ *       inputSchema: {
+ *         type: "object",
+ *         properties: { sku: { type: "string", description: "Référence" } },
+ *         required: ["sku"],
+ *       },
+ *       handler: async (args) => mcpText(await this.stock(String(args.sku))),
+ *     }];
+ *   }
+ * }
+ * ```
+ */
+export interface IMcpTool extends IMcpToolDefinition {
+    /**
+     * Scopes OAuth exigés — **tous**, pas au moins un.
+     *
+     * Absent = outil public, servi à qui atteint la porte. Présent, l'outil est
+     * **retenu** tant que l'appelant ne les présente pas : il n'apparaît pas dans
+     * `tools/list` ET n'est pas appelable en le nommant — un catalogue filtré qui
+     * resterait appelable ne serait qu'un rideau.
+     *
+     * La spec le permet explicitement (`server/tools`) : le jeu d'outils « MAY
+     * vary by the authorization presented on the request — for example, returning
+     * only the tools the caller's granted scopes permit ». Elle interdit en
+     * revanche de le faire varier PAR CONNEXION : c'est pourquoi la décision se
+     * prend sur les identifiants de la requête, jamais sur un état retenu.
+     */
+    scopes?: readonly string[];
+    /**
+     * Exige une identité prouvée, sans scope particulier.
+     *
+     * Utile quand l'outil filtre lui-même ce qu'il rend selon
+     * {@link IMcpCaller.subject} — « mes commandes », « mes tâches ». Déclarer
+     * des {@link IMcpTool.scopes} l'implique déjà.
+     */
+    requiresAuth?: boolean;
+    /**
+     * Implémentation. Un échec métier se rend en `isError`, pas en exception.
+     *
+     * Le second paramètre porte l'appelant ÉTABLI : un outil authentifié doit
+     * pouvoir borner ce qu'il rend à son sujet, et pas seulement décider s'il
+     * répond. Un handler qui l'ignore reste parfaitement valide.
+     */
+    handler: (args: Record<string, unknown>, caller: IMcpCaller) => IMcpToolResult | Promise<IMcpToolResult>;
+}

package/dist/client/types/src/types/IModule.d.ts

@@ -0,0 +1,73 @@
+import type { IService } from "./IService.js";
+import type { IKernel } from "./IKernel.js";
+import type { JSONObject } from "./globals.js";
+import type { IMcpTool } from "./IMcpTool.js";
+/**
+ * Constructeur générique de controller — équivalent au type historique
+ * `TypeController<T>` mais exposé via le contract public IModule.
+ * Permet aux consommateurs (framework, http, security) de typer leurs
+ * controllers sans que le core dépende de @nodefony/framework.
+ */
+export type IControllerConstructor<T = unknown> = new (...args: any[]) => T;
+export interface PackageJson {
+    name: string;
+    version: string;
+    description?: string;
+    main?: string;
+    module?: string;
+    types?: string;
+    scripts?: Record<string, string>;
+    repository?: {
+        type: string;
+        url: string;
+    };
+    keywords?: string[];
+    author?: string;
+    license?: string;
+    dependencies?: Record<string, string>;
+    devDependencies?: Record<string, string>;
+    peerDependencies?: Record<string, string>;
+    [key: string]: unknown;
+}
+/**
+ * Contrat public d'un module nodefony.
+ * Module.ts implémente cette interface.
+ *
+ * Types Rollup/RollupWatcher/Controller typés unknown — dépendances externes
+ * non disponibles ici sans créer des imports circulaires ou des couplages forts.
+ */
+export interface IModule extends IService {
+    path: string;
+    isApp: boolean;
+    package?: PackageJson;
+    onKernelRegister?(): Promise<this>;
+    onKernelBoot?(): Promise<this>;
+    onKernelReady?(): Promise<this>;
+    init?(kernel?: IKernel): Promise<this>;
+    addService(service: unknown, ...args: any[]): Promise<IService>;
+    loadService(service: string, ...args: unknown[]): Promise<IService>;
+    getDependencies(): string[];
+    getController<T = unknown>(name: string): IControllerConstructor<T>;
+    getControllers<T = unknown>(): Record<string, IControllerConstructor<T>>;
+    getServiceNames(): string[];
+    /**
+     * Outils que ce module ajoute à la porte MCP de l'application.
+     *
+     * Optionnel et **lu à la demande** — jamais au boot : un serveur MCP les
+     * ramasse au moment de servir `tools/list`, ce qui ne coûte rien tant que
+     * personne n'appelle, et rend la liste toujours fraîche. Le module capture par
+     * fermeture ce dont ses handlers ont besoin (`this`, ses services).
+     *
+     * Une déclaration qui lève, rend autre chose qu'un tableau, porte un nom hors
+     * forme ou déjà pris est ÉCARTÉE avec un motif journalisé — jamais en silence,
+     * sinon son auteur chercherait la faute dans un handler jamais appelé.
+     */
+    getMcpTools?(): IMcpTool[];
+    configSchema(): unknown | null;
+    getPackageJson(cwd?: string): Promise<PackageJson>;
+    getModuleName(): string | undefined;
+    getModuleVersion(): string | undefined;
+    install(force?: boolean): Promise<number | Error>;
+    outdated(): Promise<number | Error>;
+    loadJson(url: string, cwd?: string): Promise<JSONObject>;
+}