@nodefony/devkit 10.0.0-alpha.1

package/dist/nodefony/src/mcp/tools.js

@@ -0,0 +1,163 @@
+import { INSPECT_SUBJECTS, collectCheckReport, countCheckFindings, lookupSymbol, readAdminSubject, readSymbolsGraph } from "nodefony";
+//#region nodefony/src/mcp/tools.ts
+/** Préfixe des noms d'outils — un agent voit à qui il parle. */
+const PREFIX = "nodefony_";
+/**
+* Liste des sujets, rendue lisible pour la description de l'outil.
+*
+* Dérivée de {@link INSPECT_SUBJECTS} : ajouter un sujet au cœur le publie ici
+* sans rien réécrire, et il ne peut pas exister de sujet annoncé qu'on ne
+* saurait pas lire.
+*/
+function subjectLines() {
+	return Object.entries(INSPECT_SUBJECTS).map(([key, spec]) => `- \`${key}\` : ${spec.summary}`).join("\n");
+}
+/** Catalogue complet, avant filtrage par l'allowlist de configuration. */
+function catalogue() {
+	return {
+		inspect: {
+			name: `${PREFIX}inspect`,
+			description: `Lit l'état RÉEL de cette application Nodefony : les routes réellement montées, les modules chargés, les services enregistrés, la configuration effective et la provenance de chaque valeur, les stores de données, les entités de l'ORM. À utiliser avant d'écrire du code qui suppose une route, un service ou une clé de configuration — la réponse vient de l'application qui tourne, pas d'une lecture des sources, donc elle ne peut pas se tromper sur ce qui est chargé.
+
+Sujets disponibles :\n${subjectLines()}`,
+			inputSchema: {
+				type: "object",
+				properties: {
+					subject: {
+						type: "string",
+						enum: Object.keys(INSPECT_SUBJECTS),
+						description: "Ce qu'on veut voir"
+					},
+					target: {
+						type: "string",
+						description: "Paramètre du sujet, quand il en attend un (ex. le nom d'un module pour `module`)"
+					}
+				},
+				required: ["subject"]
+			}
+		},
+		card: {
+			name: `${PREFIX}card`,
+			description: "Carte de visite de l'application : son identité, les modules chargés, où trouver la documentation, et les commandes à lancer. À utiliser en ARRIVANT sur une application inconnue, avant toute autre exploration — elle dit en un appel ce qu'il y a et où aller ensuite.",
+			inputSchema: {
+				type: "object",
+				properties: {}
+			}
+		},
+		check: {
+			name: `${PREFIX}check`,
+			description: "Diagnostic STATIQUE de l'application : classes écrites que rien n'enregistre (entité, controller ou service jamais câblé), paquets importés sans être déclarés, variables d'environnement requises absentes, modules du manifeste non installés, ports occupés, et le bilan du dernier démarrage. À utiliser APRÈS avoir écrit ou généré du code, avant de conclure que c'est fini : ni la compilation ni les tests ne voient qu'une classe n'est branchée à rien.",
+			inputSchema: {
+				type: "object",
+				properties: {}
+			}
+		},
+		symbols: {
+			name: `${PREFIX}symbols`,
+			description: "Interroge le graphe symbolique du framework : ce qu'est un symbole (classe, interface, fonction), où il est défini, ce qu'il étend ou implémente, et la première phrase de sa documentation. À utiliser AVANT d'ouvrir un fichier pour comprendre une API du framework — la réponse est immédiate et vaut pour la version réellement installée. Sans argument, rend le résumé du graphe ; avec `module`, la surface exportée d'un paquet.",
+			inputSchema: {
+				type: "object",
+				properties: {
+					name: {
+						type: "string",
+						description: "Nom exact du symbole (ex. `AbstractCrudService`, `IKernel`)"
+					},
+					module: {
+						type: "string",
+						description: "Paquet dont on veut la surface exportée (ex. `@nodefony/http`)"
+					}
+				}
+			}
+		}
+	};
+}
+/**
+* Outils publiés, filtrés par l'allowlist de configuration.
+*
+* Une clé inconnue dans la configuration est simplement ignorée : elle ne peut
+* rien ouvrir. C'est le sens d'une allowlist — ce qui n'est pas nommé ICI
+* n'existe pas, et la faute de frappe d'un utilisateur ne peut pas activer
+* autre chose que ce qu'il voulait.
+*
+* ⚠️ **`Object.hasOwn` n'est pas une précaution de style.** Sans lui,
+* `tools: ["toString"]` résolvait une méthode héritée d'`Object.prototype` :
+* la valeur n'étant pas `undefined`, elle franchissait le filtre et un outil
+* fantôme entrait dans le catalogue publié. Trouvé par le test, pas à la
+* relecture.
+*
+* @param enabled - clés d'outils autorisées (`devkit.mcp.tools`)
+*/
+function listMcpTools(enabled) {
+	const all = catalogue();
+	return enabled.filter((key) => Object.hasOwn(all, key)).map((key) => all[key]).filter((tool) => tool !== void 0);
+}
+/** Rend un contenu textuel — les données partent en JSON indenté, lisible. */
+function text(value, isError = false) {
+	const rendered = typeof value === "string" ? value : JSON.stringify(value, null, 2);
+	return isError ? {
+		content: [{
+			type: "text",
+			text: rendered
+		}],
+		isError: true
+	} : { content: [{
+		type: "text",
+		text: rendered
+	}] };
+}
+/**
+* Exécute un outil par son nom public.
+*
+* Un échec métier (sujet inconnu, module absent) rend un résultat `isError`,
+* **pas** une erreur JSON-RPC : le protocole réserve celle-ci 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.
+*
+* @param name - nom public de l'outil (`nodefony_inspect`…)
+* @param args - arguments fournis par l'agent
+* @param enabled - allowlist de configuration
+* @param deps - briques qui répondent réellement
+* @returns le résultat de l'outil, ou `null` si le nom n'est pas exposé
+*/
+async function callMcpTool(name, args, enabled, deps) {
+	if (!listMcpTools(enabled).find((tool) => tool.name === name)) return null;
+	if (name === `${PREFIX}card`) return text(deps.getCard());
+	if (name === `${PREFIX}inspect`) {
+		const subject = typeof args.subject === "string" ? args.subject : "";
+		const target = typeof args.target === "string" ? args.target : void 0;
+		const read = await readAdminSubject(deps.broker, subject, target);
+		if (!read.ok) return text(read.message, true);
+		return text(read.data);
+	}
+	if (name === `${PREFIX}check`) {
+		const report = await collectCheckReport(deps.projectRoot);
+		return text({
+			verdict: countCheckFindings(report) === 0 ? "ok" : "manquements",
+			total: countCheckFindings(report),
+			...report
+		});
+	}
+	if (name === `${PREFIX}symbols`) {
+		const graph = readSymbolsGraph(deps.projectRoot);
+		if (graph === null) return text("aucun graphe symbolique atteignable — il est publié par le paquet `nodefony` (node_modules/nodefony/.ai/symbols.json) et régénérable dans ce dépôt par `npm run generate-symbols`", true);
+		const wanted = typeof args.name === "string" ? args.name : null;
+		const module = typeof args.module === "string" ? args.module : null;
+		if (wanted !== null) {
+			const sym = lookupSymbol(graph, wanted);
+			return sym ? text(sym) : text(`« ${wanted} » est introuvable dans le graphe (${Object.keys(graph.symbols).length} symboles)`, true);
+		}
+		const entries = Object.values(graph.symbols).filter((s) => module === null || s.module === module);
+		if (module !== null) return text(entries.sort((a, b) => a.name.localeCompare(b.name)));
+		const parPaquet = Object.create(null);
+		for (const sym of entries) parPaquet[sym.module] = (parPaquet[sym.module] ?? 0) + 1;
+		return text({
+			total: entries.length,
+			parPaquet
+		});
+	}
+	return text(`outil « ${name} » publié mais non implémenté`, true);
+}
+//#endregion
+export { callMcpTool, listMcpTools };

package/dist/types/index.d.ts

@@ -0,0 +1,52 @@
+import { Kernel, Module } from "nodefony";
+import { type DevkitConfigInput } from "./nodefony/config/config.js";
+import DevkitService from "./nodefony/service/DevkitService.js";
+import DevkitController from "./nodefony/controllers/DevkitController.js";
+import McpController from "./nodefony/controllers/McpController.js";
+/**
+ * @nodefony/devkit — Outillage de developpement d une application Nodefony : carte de visite et portes de decouverte pour un agent
+ *
+ * Module applicatif : un workspace npm à part entière
+ * (`src/packages/@nodefony/devkit/`), chargé par le manifeste `modules` de
+ * `nodefony.config.ts`. Le Kernel l'importe PAR SON NOM (`@nodefony/devkit`) —
+ * d'où le workspace, qui le rend résolvable.
+ */
+/**
+ * Rend la config du module typée à l'appel : `use("@nodefony/devkit", { … })`
+ * dans `nodefony.config.ts` propose les clés du schéma et refuse les fautes de
+ * frappe, au lieu d'avaler un `Record<string, unknown>`.
+ */
+declare module "nodefony" {
+    interface NodefonyModuleConfig {
+        "@nodefony/devkit": DevkitConfigInput;
+    }
+}
+declare class DevkitModule extends Module {
+    /**
+     * ⚠️ Ce module ne pose PLUS de commande CLI.
+     *
+     * `devkit:card` vivait ici, et n'existait donc que lorsque le module était
+     * chargé : hors développement (`policy: "dev"`) le CLI répondait
+     * `unknown command`, et sur une application non encore construite le Kernel
+     * refusait de démarrer avant elle. Une carte de visite qui disparaît selon
+     * l'environnement n'accueille personne. Elle est désormais servie par le cœur
+     * (`nodefony card`, alias `devkit:card`, standalone 0-boot — fast-path de
+     * `CliKernel.start`), qui ne lit que des fichiers.
+     *
+     * Ce module garde la porte HTTP : elle, et elle seule, connaît les modules
+     * réellement CHARGÉS.
+     */
+    constructor(kernel: Kernel);
+    /**
+     * Valide la config au boot — défauts du schéma fusionnés avec ce que l'app
+     * passe dans `use()`. Une clé inconnue ou mal typée plante ICI, avec le champ
+     * fautif nommé, plutôt qu'en `undefined.x` au premier appel en production.
+     */
+    onKernelRegister(): Promise<this>;
+}
+export default DevkitModule;
+export { DevkitService, DevkitController, McpController };
+export { buildCard } from "./nodefony/src/card.js";
+export { defineDevkitConfig } from "./nodefony/config/defineModuleConfig.js";
+export { devkitConfigSchema, type DevkitConfig, type DevkitConfigInput, } from "./nodefony/config/config.js";
+export type { IDevkitAppInfo, IDevkitCard, IDevkitCardInput, IDevkitDoor, IDevkitService, IDevkitVerb, } from "./nodefony/interfaces/IDevkitService.js";

package/dist/types/nodefony/command/CardCommand.d.ts

@@ -0,0 +1,33 @@
+import { Command, CliKernel } from "nodefony";
+import type { IDevkitCard } from "../interfaces/IDevkitService.js";
+/**
+ * `nodefony devkit:card [-j]` — qui répond, et où aller ensuite.
+ *
+ * ## Pourquoi une commande, alors que la route existe
+ *
+ * La route HTTP vit sous `/nodefony`, que le pare-feu d'une application réelle
+ * couvre : un agent qui code ne s'authentifie pas, et n'a pas de navigateur. La
+ * porte qu'il a déjà, c'est le terminal. Même source (le service), deux rendus —
+ * ajouter une porte n'ajoute jamais une vérité.
+ *
+ * ⚠️ Le module est `policy: "dev"` : hors développement il n'est pas chargé, donc
+ * cette commande **n'existe pas**. C'est voulu — et c'est pour ça qu'elle
+ * s'invoque `NODE_ENV=development npx nodefony devkit:card` depuis un terminal
+ * qui n'aurait pas posé la variable.
+ */
+declare class CardCommand extends Command {
+    constructor(cli: CliKernel);
+    generate(opts: {
+        json?: boolean;
+    }): Promise<this>;
+    /**
+     * Rend la carte pour un HUMAIN (ou un agent qui lit un terminal).
+     *
+     * Statique et PURE : elle ne touche ni au kernel ni au service, donc elle
+     * s'éprouve seule. Sortie sur `stdout` plutôt que par le journal — une carte
+     * de visite n'est pas un événement de log, et le préfixe horodaté rendrait le
+     * copier-coller inutilisable.
+     */
+    static format(card: IDevkitCard): string;
+}
+export default CardCommand;

package/dist/types/nodefony/config/config.d.ts

@@ -0,0 +1,25 @@
+import { z } from "zod";
+export declare const devkitConfigSchema: z.ZodObject<{
+    enabled: z.ZodDefault<z.ZodBoolean>;
+    mcp: z.ZodDefault<z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        allowedOrigins: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        allowRemote: z.ZodDefault<z.ZodBoolean>;
+        tools: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        authorization: z.ZodDefault<z.ZodObject<{
+            authorizationServers: z.ZodDefault<z.ZodArray<z.ZodString>>;
+            resource: z.ZodDefault<z.ZodString>;
+            additionalResources: z.ZodDefault<z.ZodArray<z.ZodString>>;
+            resourceName: z.ZodOptional<z.ZodString>;
+            resourceDocumentation: z.ZodOptional<z.ZodString>;
+            anonymous: z.ZodDefault<z.ZodBoolean>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+/** Config telle que l'APP l'écrit dans `use()` — tous les champs optionnels. */
+export type DevkitConfigInput = z.input<typeof devkitConfigSchema>;
+/** Config telle que le CODE la lit — défauts appliqués, rien d'optionnel. */
+export type DevkitConfig = z.output<typeof devkitConfigSchema>;
+/** Défauts matérialisés (passés au `super()` du Module). */
+declare const defaults: DevkitConfig;
+export default defaults;

package/dist/types/nodefony/config/defineModuleConfig.d.ts

@@ -0,0 +1,27 @@
+import type { DevkitConfig, DevkitConfigInput } from "./config.js";
+/**
+ * @nodefony/devkit — LE COMMENT : builder PUR de la config.
+ *
+ * ⭐ TL;DR : ce fichier VALIDE et GÈLE. Il ne porte AUCUNE valeur — les défauts
+ * vivent dans le schéma de `./config.ts` (règle d'or ADR-0006). Pour changer un
+ * défaut, c'est là-bas ; ici, on ne fait que le faire respecter.
+ *
+ * Le nom du FICHIER est le même dans tous les modules Nodefony
+ * (`defineModuleConfig.ts`) ; la FONCTION, elle, est préfixée par le module —
+ * deux modules importés côte à côte ne se marchent pas dessus.
+ *
+ * L'override env générique (`NF__DEVKIT__<CHEMIN>`) est appliqué par le core,
+ * pas ici. Si le module a besoin d'une variable d'env DÉDIÉE, elle s'applique
+ * APRÈS le parse, dans cette fonction, pour que le schéma reste pur.
+ *
+ * @param config - config brute venue de `use("@nodefony/devkit", { … })`.
+ * @returns config validée et gelée.
+ * @throws BootConfigurationError si un champ est invalide ou une clé inconnue
+ *   (anomalies Zod agrégées) — le boot s'interrompt, en dev comme en prod.
+ */
+export declare function defineDevkitConfig(config?: DevkitConfigInput): DevkitConfig;
+/**
+ * JSON Schema de la config — Studio en dérive son formulaire d'édition
+ * (libellés, types, défauts, descriptions), sans une ligne d'UI écrite à la main.
+ */
+export declare function devkitConfigJsonSchema(): unknown;

package/dist/types/nodefony/controllers/DevkitController.d.ts

@@ -0,0 +1,37 @@
+import { Controller } from "@nodefony/framework";
+import type { ContextType } from "@nodefony/http";
+/**
+ * La carte de visite de l'application, servie en HTTP.
+ *
+ * ## Pourquoi cette route n'est pas `/`
+ *
+ * Ce qu'elle rend — modules chargés, chemins de documentation, commandes à
+ * lancer — aide pendant le développement et n'est, en production, qu'une
+ * divulgation de l'architecture. Elle vit donc dans un module `policy: "dev"`,
+ * absent du boot en production, et sous le préfixe réservé `/nodefony` plutôt
+ * qu'à la racine : `/` appartient à l'application, qui doit pouvoir y répondre
+ * ce qu'elle assume devant ses utilisateurs.
+ *
+ * ## Pourquoi aucune garde `@IsGranted`
+ *
+ * Le module n'existe qu'en développement : c'est la `policy` qui le protège, pas
+ * un rôle. Exiger un rôle imposerait `@nodefony/security` à toute application
+ * qui installe le devkit — y compris celles qui n'ont pas de firewall du tout.
+ * Une garde qui force une dépendance protège moins qu'elle ne coûte.
+ *
+ * **Mince par design** : la composition de la carte vit dans le service (et sa
+ * construction dans une fonction pure) ; le controller ne fait que traduire en
+ * HTTP.
+ */
+declare class DevkitController extends Controller {
+    #private;
+    constructor(context: ContextType);
+    /**
+     * `GET /nodefony/devkit/api/card` — qui répond, et où aller ensuite.
+     *
+     * La réponse est recalculée à chaque appel : elle décrit l'application TELLE
+     * QU'ELLE EST, pas telle qu'elle était au démarrage.
+     */
+    card(): Promise<import("@nodefony/http").Http2Response | import("@nodefony/http").HttpResponse | import("@nodefony/http").WebsocketResponse>;
+}
+export default DevkitController;

package/dist/types/nodefony/controllers/McpController.d.ts

@@ -0,0 +1,70 @@
+import { Controller } from "@nodefony/framework";
+import type { ContextType } from "@nodefony/http";
+/**
+ * Serveur **Model Context Protocol** de l'application — la porte par laquelle
+ * un agent externe l'interroge.
+ *
+ * ## Pourquoi une route, et pas un process
+ *
+ * La révision `2026-07-28` du transport « Streamable HTTP » a supprimé les
+ * sessions de niveau protocole et le flux `GET` : il ne reste qu'**un endpoint
+ * qui accepte `POST`**, chaque message étant autonome. Un serveur MCP n'a donc
+ * plus besoin d'être un process séparé lancé par le client — c'est une route de
+ * l'application, qui tourne déjà. Conséquence directe en développement : quand
+ * le superviseur relance le serveur sur une sauvegarde, rien n'est perdu, et la
+ * réponse suivante vient du code qui vient d'être rechargé. Aucun cache à
+ * invalider — la fraîcheur est une propriété du protocole.
+ *
+ * ## Ce qui protège cette route
+ *
+ * **Par défaut, le périmètre — et lui seul.** Ce module est `policy: "dev"`,
+ * donc cette route n'existe pas en production ; restent les deux gardes que la
+ * spec impose au transport, portées par {@link checkMcpAccess} : l'en-tête
+ * `Origin` et la localité de l'appelant. Elles visent le seul vecteur réel
+ * contre un serveur local — une page web ouverte dans le navigateur du
+ * développeur.
+ *
+ * **Dès qu'un serveur d'autorisation est déclaré** (`mcp.authorization`), la
+ * porte prend son rôle de *resource server* OAuth 2.1 : elle publie ses
+ * métadonnées (RFC 9728, publiées par `@nodefony/framework` depuis
+ * `DevkitService.publishedProtectedResources()`), valide le porteur
+ * présenté, et refuse en citant `resource_metadata` — l'en-tête qui apprend au
+ * client où obtenir un jeton (RFC 6750). L'audience attendue est l'URI
+ * canonique de la porte (RFC 8707) : c'est ce qui empêche un jeton émis pour un
+ * autre service d'être rejoué ici.
+ *
+ * ⚠️ **Le serveur d'AUTORISATION n'est pas de notre ressort**, et ne l'a jamais
+ * été : la spec le place « beyond the scope […] or a separate entity ». Avoir
+ * écrit l'inverse a servi d'excuse à ne rien faire pendant tout un cycle.
+ *
+ * 🔴 **La vérification du jeton est déléguée, et son absence est fatale.** Ce
+ * module ne peut pas dépendre de `@nodefony/security` (il disparaît en
+ * production, pas elle) : il cherche un `accessTokenVerifier` dans le conteneur
+ * — nom GÉNÉRIQUE, car le contrat prend l'audience en paramètre : un seul
+ * vérificateur sert toutes les ressources protégées d'une application, celle-ci
+ * étant seulement la première.
+ * Rôle déclaré + aucun vérificateur = `503` et journal `CRITIC`, jamais une
+ * porte qui laisse passer les porteurs sans les lire.
+ *
+ * **Mince par design** : tout le protocole vit AU CŒUR (`nodefony`, en fonctions
+ * pures) ; ce controller ne fait que traduire HTTP ↔ JSON-RPC et fournir au
+ * collecteur ce que lui seul connaît — le service du module, le broker
+ * d'administration, la racine du projet. C'est ce qui permet à un autre module
+ * d'ouvrir la même porte ailleurs (en production, sous authentification) sans
+ * réécrire une ligne de protocole.
+ */
+declare class McpController extends Controller {
+    #private;
+    constructor(context: ContextType);
+    /**
+     * `POST /nodefony/mcp` — un message JSON-RPC entre, une réponse sort.
+     *
+     * Les trois statuts que rend cette route sont ceux que la spec impose, et pas
+     * un de plus : `202` sans corps pour une notification acceptée, `403` pour un
+     * appel dont l'origine ou l'adresse est refusée, `404` pour une méthode
+     * inconnue (afin de la distinguer d'un serveur qui n'hébergerait pas
+     * d'endpoint MCP du tout).
+     */
+    mcp(body: unknown, origin?: string, protocolVersion?: string, authorization?: string): Promise<import("@nodefony/http").Http2Response | import("@nodefony/http").HttpResponse | import("@nodefony/http").WebsocketResponse>;
+}
+export default McpController;

package/dist/types/nodefony/controllers/OAuthMetadataController.d.ts

@@ -0,0 +1,39 @@
+import { Controller } from "@nodefony/framework";
+import type { ContextType } from "@nodefony/http";
+/**
+ * Métadonnées OAuth 2.1 de la porte MCP — **le seul moyen normalisé** pour
+ * qu'un agent apprenne où obtenir un jeton.
+ *
+ * ## Pourquoi un controller séparé
+ *
+ * Trois raisons, et aucune n'est esthétique. Le chemin vit **hors** du préfixe
+ * `/nodefony` (la RFC impose `/.well-known/…` juste après l'hôte). Le document
+ * est **public par conception** — un client doit pouvoir le lire avant d'avoir
+ * le moindre jeton, donc il ne porte ni garde d'origine ni exigence de
+ * localité, contrairement à la porte elle-même. Et il répond en `GET`, quand la
+ * porte n'accepte que `POST`.
+ *
+ * ## Ce que publier coûte, et ce que ne rien publier coûte
+ *
+ * Le document ne révèle rien de sensible : l'émetteur des jetons, les scopes
+ * compris, un nom. En revanche, ne PAS le publier a un coût mesuré — un client
+ * qui ne le trouve pas suppose que le serveur d'autorisation est le serveur
+ * lui-même, et part sonder des chemins qui n'existent pas. C'est exactement ce
+ * qui a produit le bruit OAuth observé sur cette porte.
+ *
+ * 🔴 **Rôle éteint = `404`, jamais un document vide.** Un document sans serveur
+ * d'autorisation apprendrait au client qu'un jeton est nécessaire sans jamais
+ * lui dire où le demander : la spécification MCP l'interdit d'ailleurs
+ * explicitement (« MUST include […] at least one authorization server »).
+ */
+declare class OAuthMetadataController extends Controller {
+    #private;
+    constructor(context: ContextType);
+    /**
+     * `GET /.well-known/oauth-protected-resource/nodefony/mcp` — RFC 9728 §3.
+     *
+     * @returns le document JSON, ou `404` si cette porte n'est pas protégée
+     */
+    metadata(): Promise<import("@nodefony/http").Http2Response | import("@nodefony/http").HttpResponse | import("@nodefony/http").WebsocketResponse>;
+}
+export default OAuthMetadataController;

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

@@ -0,0 +1,69 @@
+import type { ICard, ICardAppInfo, ICardDoor, ICardInput, ICardVerb, IMcpToolDeps } from "nodefony";
+import type { DevkitConfig } from "../config/config.js";
+/**
+ * Le contrat de la carte est celui du CŒUR — ces noms n'en sont que les alias,
+ * conservés parce qu'ils forment la surface publique de ce module.
+ *
+ * La forme de la carte ne peut avoir qu'une définition : la CLI
+ * (`nodefony card`, standalone 0-boot) et la porte HTTP de ce module rendent le
+ * MÊME objet. Deux déclarations parallèles auraient divergé au premier champ
+ * ajouté, et chacune aurait passé ses propres tests.
+ */
+export type IDevkitCard = ICard;
+/** Identité de l'application qui répond. */
+export type IDevkitAppInfo = ICardAppInfo;
+/** Une PORTE : un endroit où aller chercher la suite. */
+export type IDevkitDoor = ICardDoor;
+/** Un VERBE : une commande à lancer (toujours préfixée `npx`). */
+export type IDevkitVerb = ICardVerb;
+/** L'état minimal dont la carte se dérive — injecté, jamais lu. */
+export type IDevkitCardInput = ICardInput;
+/**
+ * API publique de `DevkitService` (injectable, nom `devkit`).
+ *
+ * L'interface est le CONTRAT : ce que les autres modules (et Studio) peuvent
+ * appeler. Tout ce qui n'est pas ici est un détail d'implémentation, libre de
+ * changer.
+ */
+export interface IDevkitService {
+    /** Snapshot de lecture — état courant du service. */
+    status(): {
+        ready: boolean;
+    };
+    /**
+     * Carte de visite de l'application, DÉRIVÉE de l'état du Kernel.
+     *
+     * Le module ne stocke rien en propre : ce qu'il rend est recalculé à la
+     * lecture. Une carte mise en cache mentirait au premier module ajouté.
+     *
+     * Ici — et ici seulement — la liste des modules est celle des modules
+     * réellement CHARGÉS (`source: "runtime"`) : le Kernel tourne, le gating
+     * `policy`/`when` a déjà eu lieu. La porte CLI, elle, répond à froid et le
+     * DIT.
+     */
+    getCard(): IDevkitCard;
+    /**
+     * Réglages effectifs du serveur MCP (défauts du schéma + surcharges de l'app).
+     *
+     * Exposé sur le contrat parce que la porte HTTP les lit : gardes d'accès et
+     * allowlist d'outils viennent d'ICI, jamais d'une seconde lecture de la
+     * configuration — deux lectures divergent.
+     */
+    mcpSettings(): DevkitConfig["mcp"];
+    /**
+     * Ce dont les outils MCP intégrés ont besoin pour répondre.
+     *
+     * Sur le contrat parce que la porte HTTP les passe au catalogue : les
+     * composer de son côté ferait une seconde source, qui divergerait de celle
+     * dont sont dérivés les scopes publiés.
+     */
+    mcpToolDeps(): IMcpToolDeps;
+    /**
+     * Les scopes que la porte MCP EXIGE, dérivés des outils déclarés.
+     *
+     * Deux lecteurs, une seule source : le document RFC 9728 (`scopes_supported`)
+     * et le défi opposé à un porteur refusé (RFC 6750 `scope`). Vide = la porte
+     * n'exige rien, et le champ est alors omis du document.
+     */
+    declaredMcpScopes(): readonly string[];
+}

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

@@ -0,0 +1 @@
+export type { IDevkitService } from "./IDevkitService.js";