@nodefony/devkit 10.0.0-beta.2 → 10.0.0-beta.4

package/dist/types/nodefony/mcp/profileRoute.d.ts

@@ -0,0 +1,87 @@
+import { type IMcpCaller, type IMcpTool, type IRolesWithin } from "nodefony";
+import { type IProfilerReader } from "@nodefony/http";
+import { type IObserveProbe } from "./observe.js";
+import { type RequestLogs } from "./profileReport.js";
+import { type IShotClient, type IShotTarget } from "./shotClient.js";
+import { type OnShutdown } from "./shutdown.js";
+/** Requêtes mesurées par défaut. */
+export declare const PROFILE_ROUTE_DEFAULT_COUNT = 50;
+/**
+ * Requêtes mesurées au plus. Avec la chauffe, sous les 500 profils que garde le
+ * profileur : au-delà, les premiers seraient évincés avant d'être lus.
+ */
+export declare const PROFILE_ROUTE_MAX_COUNT = 200;
+/** Requêtes simultanées par défaut. */
+export declare const PROFILE_ROUTE_DEFAULT_CONCURRENCY = 4;
+/** Requêtes simultanées au plus : mesurer une route, pas saturer le process. */
+export declare const PROFILE_ROUTE_MAX_CONCURRENCY = 8;
+/** Requêtes de chauffe par défaut, tirées AVANT et hors des mesures. */
+export declare const PROFILE_ROUTE_DEFAULT_WARMUP = 3;
+/** Requêtes de chauffe au plus. */
+export declare const PROFILE_ROUTE_MAX_WARMUP = 20;
+/**
+ * Budget de temps d'un tir, en ms. Sous les 60 s qu'un client MCP attend par
+ * défaut : au-delà, l'agent couperait l'appel juste avant le rapport.
+ */
+export declare const PROFILE_ROUTE_BUDGET_MS = 45000;
+/**
+ * Attente maximale, en ms, d'un profil après la réponse : le profileur le
+ * collecte au `close` de la réponse, émis en différé — rien ne garantit qu'il
+ * précède la fin de lecture côté client, dans le même process.
+ */
+export declare const PROFILE_COLLECT_WAIT_MS = 500;
+/** Ce dont l'outil a besoin — injecté, pour l'éprouver sans application. */
+export interface IProfileRouteDeps {
+    /** Le profileur de l'application, ou `undefined` hors développement. */
+    getProfiler: () => IProfilerReader | undefined;
+    /**
+     * Ce process sert-il des requêtes ? Rend `false` sous la porte stdio :
+     * l'outil le dit ({@link NOT_SERVING_MESSAGE}). Absent : supposé servir.
+     */
+    servesTraffic?: (() => boolean) | undefined;
+    /** L'adresse d'écoute HTTP en clair de l'application, ou `null`. */
+    getTarget: () => IShotTarget | null;
+    /** Fabrique du client du tir (défaut : `node:http`, cf {@link createShotClient}). */
+    createClient?: ((target: IShotTarget, concurrency: number) => IShotClient) | undefined;
+    /** Fabrique de la sonde du process (défaut : `ProcessProbe` du cœur). */
+    createProbe?: (() => IObserveProbe) | undefined;
+    /** Émet le ticket à usage unique qui ouvrira la session de `identifier`. */
+    issueTicket?: ((identifier: string) => string) | undefined;
+    /** Détruit la session de profilage désignée par son pseudonyme. */
+    closeSession?: ((ref: string) => Promise<unknown>) | undefined;
+    /** Les rôles de `target` sont-ils inclus dans ceux de `owner` (hiérarchie comprise) ? */
+    rolesWithin?: IRolesWithin | undefined;
+    /** Lit les lignes de journal d'une requête en erreur. */
+    readRequestLogs?: ((requestId: string, caller: IMcpCaller) => Promise<RequestLogs>) | undefined;
+    /** S'abonne à l'arrêt du serveur pour la durée d'un appel. */
+    onShutdown?: OnShutdown | undefined;
+    /** Attente d'un profil après sa réponse (défaut {@link PROFILE_COLLECT_WAIT_MS}). */
+    collectWaitMs?: number | undefined;
+    /** Budget du tir (défaut {@link PROFILE_ROUTE_BUDGET_MS}). */
+    budgetMs?: number | undefined;
+}
+/**
+ * Contrôle le chemin à profiler : un CHEMIN de l'application, jamais une URL —
+ * l'outil ne doit pouvoir viser qu'elle.
+ *
+ * @param raw - l'argument `path`, non fiable.
+ * @returns le chemin normalisé (fragment retiré), ou la raison du refus.
+ */
+export declare function checkProfilePath(raw: unknown): {
+    ok: true;
+    path: string;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * L'outil `nodefony_profile_route` : envoie lui-même N requêtes à une route de
+ * l'application, au nom d'un compte s'il le faut, et rend leur profil agrégé.
+ *
+ * Rien n'est armé hors d'un appel : le client du tir (ses connexions), la
+ * session de profilage et l'écoute de l'arrêt du serveur naissent avec l'appel
+ * et sont libérés à sa sortie, quelle qu'elle soit.
+ *
+ * @param deps - profileur, adresse d'écoute, ouverture de session, journal.
+ */
+export declare function profileRouteTool(deps: IProfileRouteDeps): IMcpTool;

package/dist/types/nodefony/mcp/shotClient.d.ts

@@ -0,0 +1,53 @@
+/** Délai d'une requête du tir, en ms : au-delà, elle compte « sans réponse ». */
+export declare const SHOT_REQUEST_TIMEOUT_MS = 15000;
+/** Où l'application écoute, vue de son propre process. */
+export interface IShotTarget {
+    /** Adresse de connexion (boucle locale). */
+    host: string;
+    port: number;
+    /** En-tête `Host` envoyé : le domaine que l'application attend. */
+    hostHeader: string;
+}
+/** Une requête du tir. */
+export interface IShotRequest {
+    method: "GET" | "HEAD" | "POST";
+    path: string;
+    headers: Readonly<Record<string, string>>;
+    /** Lire le corps de la réponse (connexion seulement ; un tir le jette). */
+    readBody?: boolean | undefined;
+}
+/** Ce que le client retient d'une réponse. */
+export interface IShotResponse {
+    status: number;
+    location: string | null;
+    setCookie: readonly string[];
+    body: string | null;
+}
+/** Le client d'UN tir : ses connexions vivent le temps de l'appel. */
+export interface IShotClient {
+    send(request: IShotRequest, signal: AbortSignal): Promise<IShotResponse>;
+    /** Ferme les connexions gardées ouvertes ; les requêtes en vol échouent. */
+    close(): void;
+}
+/**
+ * Client `node:http` d'un tir : connexions gardées ouvertes entre deux requêtes,
+ * comme un navigateur, au plus `concurrency` à la fois, toutes fermées par
+ * `close()`. Un `fetch` passerait par un pool global, qui survivrait à l'appel.
+ *
+ * @param target - l'adresse d'écoute de l'application.
+ * @param concurrency - connexions simultanées au plus.
+ * @returns le client, à fermer en fin de tir.
+ */
+export declare function createShotClient(target: IShotTarget, concurrency: number): IShotClient;
+/**
+ * Lit l'adresse d'écoute du serveur HTTP en clair de l'application (service
+ * `server-http`), telle qu'il l'a réellement obtenue — port de repli compris.
+ *
+ * Une écoute sur toutes les interfaces (`0.0.0.0`, `::`) se joint par la boucle
+ * locale : c'est aussi ce qui rend l'appel LOCAL pour la route de connexion du
+ * profilage.
+ *
+ * @param server - ce que le conteneur rend pour `server-http`.
+ * @returns la cible, ou `null` si aucun serveur n'est prêt.
+ */
+export declare function readShotTarget(server: unknown): IShotTarget | null;

package/dist/types/nodefony/mcp/shutdown.d.ts

@@ -0,0 +1,25 @@
+import type { IMcpToolRun } from "nodefony";
+/** Abonnement à l'arrêt du serveur, pour la durée d'UN appel d'outil. */
+export type OnShutdown = (listener: () => Promise<void>) => () => void;
+/** Ce qu'un outil long lit pour savoir s'il doit s'arrêter, et pourquoi. */
+export interface IToolStop {
+    /** Avorté quand l'agent abandonne l'appel OU que le serveur s'arrête. */
+    readonly signal: AbortSignal;
+    /** `true` si c'est l'arrêt du serveur qui a clos l'appel. */
+    readonly interrupted: boolean;
+    /**
+     * Le rapport est rendu : l'arrêt du serveur, s'il attendait, reprend, et
+     * l'écouteur quitte le kernel. À appeler sur TOUS les chemins de sortie.
+     */
+    release(): void;
+}
+/**
+ * Arme l'arrêt d'un outil long : l'agent qui abandonne, ou le serveur qui
+ * s'arrête (rechargement après une modification de fichier). Dans le second
+ * cas, l'arrêt attend — borné — que le rapport partiel soit parti.
+ *
+ * @param run - l'appel en cours, porteur du signal d'abandon de l'agent.
+ * @param onShutdown - abonnement à l'arrêt du serveur ; absent hors application.
+ * @returns le signal combiné, la cause, et la libération.
+ */
+export declare function watchToolStop(run: IMcpToolRun | undefined, onShutdown: OnShutdown | undefined): IToolStop;

package/dist/types/nodefony/mcp/tools.d.ts

@@ -0,0 +1,109 @@
+import { skippedChecks } from "nodefony";
+import type { IDoctorReport, IAdminBrokerLike, IMcpTool } from "nodefony";
+import type { IProfilerReader } from "@nodefony/http";
+import { type IProfileRouteDeps } from "./profileRoute.js";
+/** Ce dont les outils INTÉGRÉS ont besoin — injecté, jamais lu ici. */
+export interface IMcpToolDeps {
+    /** Le service `adminBroker` du conteneur, ou `undefined` s'il manque. */
+    broker: IAdminBrokerLike | undefined;
+    /** Compose la carte de visite de l'application. */
+    getCard: () => unknown;
+    /**
+     * Racine depuis laquelle lire le disque (graphe symbolique, diagnostic).
+     *
+     * Injectée plutôt que lue par `process.cwd()` : le serveur répond dans le
+     * process de l'application, dont le dossier courant n'est pas garanti être
+     * celui du projet — et un outil qui diagnostiquerait le mauvais dossier
+     * conclurait « rien à signaler » avec aplomb.
+     */
+    projectRoot: string;
+    /**
+     * Le profileur de développement (`"profiler"` du conteneur), ou `undefined`
+     * hors développement : `nodefony_observe` le dit au lieu de planter.
+     */
+    getProfiler: () => IProfilerReader | undefined;
+    /**
+     * Ce process sert-il des requêtes ? `false` sous la porte stdio, où les
+     * outils de MESURE refusent en le disant ; absent : supposé servir.
+     */
+    servesTraffic?: (() => boolean) | undefined;
+    /**
+     * S'abonne à l'arrêt du serveur pour la durée d'un appel (rapport partiel de
+     * `nodefony_observe`) ; absent hors application.
+     */
+    onShutdown?: ((listener: () => Promise<void>) => () => void) | undefined;
+    /**
+     * Ce que `nodefony_profile_route` demande à l'application : son adresse
+     * d'écoute, l'ouverture et la fermeture de la session de profilage, la
+     * comparaison des rôles de deux comptes. Absent hors application : l'outil
+     * dit qu'il n'a rien à viser.
+     */
+    profileRoute?: Pick<IProfileRouteDeps, "getTarget" | "issueTicket" | "closeSession" | "rolesWithin"> | undefined;
+}
+/**
+ * Clés des outils intégrés — ce que l'allowlist de configuration nomme.
+ *
+ * Publiée pour qu'un schéma de configuration puisse la valider au lieu de la
+ * retaper : une clé inconnue en config est silencieusement sans effet, et
+ * l'utilisateur croit avoir activé quelque chose.
+ */
+export declare const BUILTIN_MCP_TOOL_KEYS: readonly ["inspect", "card", "check", "symbols", "docs", "admin_list", "admin_call", "observe", "profile_route"];
+/** Clé d'un outil intégré. */
+export type BuiltinMcpToolKey = (typeof BUILTIN_MCP_TOOL_KEYS)[number];
+/** Contrôles sautés pour la MÊME raison : la raison une fois, ses familles ensuite. */
+export interface ISkippedCheckGroup {
+    /** Famille → titre, dans l'ordre de lecture du rapport. */
+    families: Record<string, string>;
+    reason: string;
+    unlock?: string | undefined;
+    onDemand?: boolean | undefined;
+    notApplicable?: boolean | undefined;
+    advisory?: boolean | undefined;
+}
+/**
+ * Regroupe les contrôles sautés qui disent exactement la même chose.
+ *
+ * Sur l'application de développement, sept familles sautées partagent trois
+ * raisons : les répéter famille par famille coûtait ~1 800 caractères à chaque
+ * appel, relus ensuite à chaque tour de l'agent.
+ *
+ * @param skipped - les contrôles sautés, dans l'ordre du rapport
+ * @returns un groupe par raison distincte, dans l'ordre de première apparition
+ */
+export declare function groupSkippedChecks(skipped: ReturnType<typeof skippedChecks>): ISkippedCheckGroup[];
+/**
+ * Taille le rapport de diagnostic pour un AGENT : les mêmes faits, sans redite.
+ *
+ * Le `--json` de `nodefony doctor` reste complet ; seule la porte MCP taille,
+ * parce que ce qu'elle rend se relit à chaque tour suivant de l'agent. Trois
+ * coupes : `execution` (que `skipped` résume déjà), les raisons de `skipped`
+ * regroupées ({@link groupSkippedChecks}), les liens `open` des derniers
+ * démarrages (faits pour un humain qui clique).
+ *
+ * @param report - le rapport de `collectDoctorReport`
+ * @returns le verdict, son compte, puis le rapport sans redite
+ */
+export declare function compactDoctorReport(report: IDoctorReport): Record<string, unknown>;
+/**
+ * Catalogue intégré du framework, indexé par clé d'allowlist.
+ *
+ * Chaque handler capture ses dépendances par fermeture : c'est ce qui permet à
+ * ces outils d'être des {@link IMcpTool} ordinaires, du même type que
+ * ceux d'une application — le serveur n'a plus aucun cas particulier à traiter.
+ *
+ * @param deps - briques qui répondent réellement
+ */
+export declare function builtinMcpTools(deps: IMcpToolDeps): Record<BuiltinMcpToolKey, IMcpTool>;
+/**
+ * Les outils du catalogue que l'allowlist de configuration retient.
+ *
+ * C'est la forme sous laquelle `@nodefony/devkit` les déclare (`getMcpTools()`) :
+ * des {@link IMcpTool} ordinaires, collectés par `@nodefony/ai` comme ceux de
+ * n'importe quel module — seul le préfixe `nodefony_`, réservé aux modules
+ * `@nodefony/*`, les distingue.
+ *
+ * @param allowlist - clés courtes retenues (cf {@link BUILTIN_MCP_TOOL_KEYS})
+ * @param deps - briques qui répondent réellement
+ * @returns les outils retenus, dans l'ordre de l'allowlist
+ */
+export declare function selectBuiltinMcpTools(allowlist: readonly string[], deps: IMcpToolDeps): IMcpTool[];

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

@@ -1,5 +1,7 @@
 import { Service, Module } from "nodefony";
-import type { IMcpToolDeps, IProtectedResourceInput } from "nodefony";
+import type { IMcpTool, IProtectedResourceInput } from "nodefony";
+import { type IMcpGate, type ITicketSessionGate } from "@nodefony/ai";
+import { type IMcpToolDeps } from "../mcp/tools.js";
 import type { IDevkitCard, IDevkitService } from "../interfaces/IDevkitService.js";
 import { type IDevkitConfig } from "../config/config.js";
 /**
@@ -12,7 +14,7 @@ import { type IDevkitConfig } from "../config/config.js";
  *
  * Un service porte DEUX noms, et c'est normal :
  *   `@injectable()`             → nomme la CLASSE (`DevkitService`),
- *                                 c'est ce qu'on écrit dans `@inject("…")`
+ *                                 c'est ce qu'on écrit dans `@Inject("…")`
  *   `super("devkit", …)` → nomme l'INSTANCE, sa clé dans le conteneur,
  *                                 c'est ce qu'on écrit dans `kernel.get("…")`
  * Les deux mènent à la MÊME instance : le conteneur les réconcilie via la classe.
@@ -28,13 +30,13 @@ import { type IDevkitConfig } from "../config/config.js";
  * ```ts
  * // 1. INJECTION par le constructeur — la dépendance est DÉCLARÉE, donc le
  * //    conteneur l'ordonnance et elle se voit dans la signature (nom de CLASSE).
- * import { inject, injectable, Service, Module } from "nodefony";
+ * import { Inject, injectable, Service, Module } from "nodefony";
  *
  * @injectable()
  * class ReportService extends Service {
  *   constructor(
  *     module: Module,
- *     @inject("DevkitService") private devkit: DevkitService,
+ *     @Inject("DevkitService") private devkit: DevkitService,
  *   ) {
  *     super("report", module.container, module.notificationsCenter);
  *   }
@@ -46,6 +48,7 @@ import { type IDevkitConfig } from "../config/config.js";
  * ```
  */
 declare class DevkitService extends Service implements IDevkitService {
+    #private;
     module: Module;
     private readonly cfg;
     constructor(module: Module);
@@ -97,6 +100,16 @@ declare class DevkitService extends Service implements IDevkitService {
      *          n'est pas garanti être celui du projet).
      */
     mcpToolDeps(): IMcpToolDeps;
+    /**
+     * Les outils `nodefony_*` retenus par l'allowlist `mcp.tools`.
+     *
+     * Recomposés à chaque appel, jamais mémorisés : la collecte a lieu à la
+     * requête MCP, sur une porte qui n'existe qu'en développement — un cache
+     * serait une structure de plus à invalider pour un gain nul.
+     *
+     * @returns les outils, dans l'ordre de l'allowlist
+     */
+    mcpTools(): IMcpTool[];
     /**
      * Les scopes que la porte MCP EXIGE — dérivés des outils qu'elle déclare.
      *
@@ -136,6 +149,30 @@ declare class DevkitService extends Service implements IDevkitService {
      * @returns une entrée pour la porte MCP, ou aucune
      */
     publishedProtectedResources(): readonly IProtectedResourceInput[];
+    /**
+     * La porte MCP de développement — définie au premier usage, une fois.
+     *
+     * Bâtie sur `defineMcpGate` comme celle de n'importe quelle application : ses
+     * réglages viennent de `devkit.mcp.*`, elle sert les outils de TOUS les modules
+     * chargés (`tools: "modules"` — l'outillage éprouve aussi ceux de l'app), et
+     * accorde le rôle d'opérateur à qui l'atteint sans jeton. Ce rôle n'est sûr que
+     * parce que son PÉRIMÈTRE la protège (module `policy: "dev"`, absent en
+     * production) ; une porte protégée par un serveur d'autorisation le tire, elle,
+     * des scopes du jeton.
+     *
+     * @returns la porte, prête à servir.
+     */
+    mcpGate(): IMcpGate;
+    /**
+     * La porte de session du profilage — définie au premier usage, une fois.
+     *
+     * Bâtie sur `defineTicketSessionGate` comme le ferait une application pour
+     * ses propres outils : locale seulement (défaut de la porte), facteur d'audit
+     * {@link PROFILE_SESSION_FACTOR}.
+     *
+     * @returns la porte, prête à émettre et à servir.
+     */
+    profileSessionGate(): ITicketSessionGate;
     status(): {
         ready: boolean;
     };

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

@@ -0,0 +1,12 @@
+/**
+ * Facteur d'authentification déclaré au flux de session : l'audit écrit
+ * `login.success` avec cette raison, ce qui distingue une session de profilage
+ * d'une vraie connexion.
+ */
+export declare const PROFILE_SESSION_FACTOR = "devkit";
+/**
+ * Chemin de la route de connexion du profilage, que l'outil appelle. Hors du
+ * motif de la zone d'administration (`^/nodefony/[^/]+/api`). Le contrôleur
+ * l'écrit en littéraux ; un test tient l'égalité.
+ */
+export declare const PROFILE_SESSION_PATH = "/nodefony/devkit/profile-session";