@nodefony/devkit 10.0.0-beta.5 → 10.0.0-beta.7

package/dist/_virtual/{_@oxc-project_runtime@0.155.0 → _@oxc-project_runtime@0.158.0}/helpers/esm/decorate.js

@@ -1,4 +1,4 @@
-// \0@oxc-project+runtime@0.155.0/helpers/esm/decorate.js
+// \0@oxc-project+runtime@0.158.0/helpers/esm/decorate.js
 function __decorate(decorators, target, key, desc) {
 	var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
 	if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);

package/dist/_virtual/{_@oxc-project_runtime@0.155.0 → _@oxc-project_runtime@0.158.0}/helpers/esm/decorateParam.js

@@ -1,4 +1,4 @@
-// \0@oxc-project+runtime@0.155.0/helpers/esm/decorateParam.js
+// \0@oxc-project+runtime@0.158.0/helpers/esm/decorateParam.js
 function __decorateParam(paramIndex, decorator) {
 	return function(target, key) {
 		decorator(target, key, paramIndex);

package/dist/index.js

@@ -1,12 +1,12 @@
-import { BUILTIN_MCP_TOOL_KEYS, builtinMcpTools, selectBuiltinMcpTools } from "./nodefony/mcp/tools.js";
 import defaults, { devkitConfigSchema } from "./nodefony/config/config.js";
 import { defineDevkitConfig } from "./nodefony/config/defineModuleConfig.js";
-import { buildCard } from "./nodefony/src/card.js";
-import __decorate from "./_virtual/_@oxc-project_runtime@0.155.0/helpers/esm/decorate.js";
 import DevkitService_default from "./nodefony/service/DevkitService.js";
 import DevkitController_default from "./nodefony/controllers/DevkitController.js";
 import McpController_default from "./nodefony/controllers/McpController.js";
 import ProfileSessionController_default from "./nodefony/controllers/ProfileSessionController.js";
+import __decorate from "./_virtual/_@oxc-project_runtime@0.158.0/helpers/esm/decorate.js";
+import { BUILTIN_MCP_TOOL_KEYS, builtinMcpTools, selectBuiltinMcpTools } from "./nodefony/mcp/tools.js";
+import { buildCard } from "./nodefony/src/card.js";
 import { Module, services } from "nodefony";
 import { controllers } from "@nodefony/framework";
 // index.ts

package/dist/nodefony/controllers/DevkitController.js

@@ -1,4 +1,4 @@
-import __decorate from "../../_virtual/_@oxc-project_runtime@0.155.0/helpers/esm/decorate.js";
+import __decorate from "../../_virtual/_@oxc-project_runtime@0.158.0/helpers/esm/decorate.js";
 import { Controller, controller, route } from "@nodefony/framework";
 // nodefony/controllers/DevkitController.ts
 /**

package/dist/nodefony/controllers/McpController.js

@@ -1,5 +1,5 @@
-import __decorate from "../../_virtual/_@oxc-project_runtime@0.155.0/helpers/esm/decorate.js";
-import __decorateParam from "../../_virtual/_@oxc-project_runtime@0.155.0/helpers/esm/decorateParam.js";
+import __decorateParam from "../../_virtual/_@oxc-project_runtime@0.158.0/helpers/esm/decorateParam.js";
+import __decorate from "../../_virtual/_@oxc-project_runtime@0.158.0/helpers/esm/decorate.js";
 import { Body, Controller, controller, route } from "@nodefony/framework";
 // nodefony/controllers/McpController.ts
 /**

package/dist/nodefony/controllers/ProfileSessionController.js

@@ -1,4 +1,4 @@
-import __decorate from "../../_virtual/_@oxc-project_runtime@0.155.0/helpers/esm/decorate.js";
+import __decorate from "../../_virtual/_@oxc-project_runtime@0.158.0/helpers/esm/decorate.js";
 import { Controller, controller, route } from "@nodefony/framework";
 // nodefony/controllers/ProfileSessionController.ts
 /**

package/dist/nodefony/mcp/profileRoute.js

@@ -1,7 +1,7 @@
-import { renderProfileReport } from "./profileReport.js";
-import { watchToolStop } from "./shutdown.js";
 import { NOT_SERVING_MESSAGE } from "./observe.js";
+import { renderProfileReport } from "./profileReport.js";
 import { SHOT_REQUEST_TIMEOUT_MS, createShotClient } from "./shotClient.js";
+import { watchToolStop } from "./shutdown.js";
 import { PROFILE_SESSION_PATH } from "../src/profileSession.js";
 import { ADMIN_SCOPE_WRITE, EVENT_LOOP_RESOLUTION_MS, ProcessProbe } from "nodefony";
 import { MCP_RESERVED_PREFIX, SESSION_TICKET_HEADER, mcpText, readTicketSessionVerdict } from "@nodefony/ai";
@@ -171,26 +171,42 @@ async function openShotSession(client, issueTicket, account, signal) {
 	} catch (error) {
 		return {
 			ok: false,
+			aborted: false,
 			message: error instanceof Error ? error.message : String(error)
 		};
 	}
-	const res = await client.send({
-		method: "POST",
-		path: PROFILE_SESSION_PATH,
-		headers: { [SESSION_TICKET_HEADER]: ticket },
-		readBody: true
-	}, signal);
+	let res;
+	try {
+		res = await client.send({
+			method: "POST",
+			path: PROFILE_SESSION_PATH,
+			headers: { [SESSION_TICKET_HEADER]: ticket },
+			readBody: true
+		}, signal);
+	} catch (error) {
+		if (error instanceof Error && error.name === "AbortError") return {
+			ok: false,
+			aborted: true
+		};
+		return {
+			ok: false,
+			aborted: false,
+			message: `session de profilage non ouverte pour \`${account}\` (${error instanceof Error ? error.message : String(error)}). L'application écoute-t-elle sur son adresse ?`
+		};
+	}
 	const read = readTicketSessionVerdict(res.body);
 	if (res.status !== 200 || "message" in read) {
 		const why = "message" in read ? read.message : `statut ${res.status}`;
 		return {
 			ok: false,
+			aborted: false,
 			message: `session de profilage non ouverte pour \`${account}\` (${res.status} — ${why}). ` + (res.status === 403 ? "Compte inconnu, inactif ou verrouillé ?" : res.status === 503 ? "" : "La route de connexion du profilage répond-elle ?")
 		};
 	}
 	const cookie = res.setCookie.map((c) => c.split(";", 1)[0] ?? "").filter((c) => c.length > 0).join("; ");
 	if (cookie.length === 0) return {
 		ok: false,
+		aborted: false,
 		message: `session ouverte pour \`${account}\`, mais aucun cookie reçu`
 	};
 	return {
@@ -417,7 +433,10 @@ async function profileRoute(profiler, target, deps, opts) {
 		if (opts.account !== null) {
 			if (deps.issueTicket === void 0) return mcpText("Profilage authentifié indisponible : aucun émetteur de ticket.", true);
 			const opened = await openShotSession(client, deps.issueTicket, opts.account, stop.signal);
-			if (!opened.ok) return mcpText(opened.message, true);
+			if (!opened.ok) {
+				if (!opened.aborted) return mcpText(opened.message, true);
+				return mcpText(stop.interrupted ? "tir interrompu avant le premier envoi : le serveur s'arrête pendant l'ouverture de la session de profilage." : "tir abandonné avant le premier envoi : la session de profilage n'était pas encore ouverte.");
+			}
 			session = opened.session;
 			headers.cookie = session.cookie;
 			identity = {

package/dist/nodefony/service/DevkitService.js

@@ -1,10 +1,10 @@
+import { selectBuiltinMcpTools } from "../mcp/tools.js";
 import { asProfilerReader } from "../mcp/observe.js";
-import { readShotTarget } from "../mcp/shotClient.js";
 import { PROFILE_SESSION_FACTOR } from "../src/profileSession.js";
-import { selectBuiltinMcpTools } from "../mcp/tools.js";
-import defaults from "../config/config.js";
+import { readShotTarget } from "../mcp/shotClient.js";
 import { buildCard } from "../src/card.js";
-import __decorate from "../../_virtual/_@oxc-project_runtime@0.155.0/helpers/esm/decorate.js";
+import defaults from "../config/config.js";
+import __decorate from "../../_virtual/_@oxc-project_runtime@0.158.0/helpers/esm/decorate.js";
 import { ADMIN_DEFAULT_ROLE, Nodefony, ROLES_WITHIN, Service, extend, injectable } from "nodefony";
 import { defineMcpGate, defineTicketSessionGate, mcpDeclaredScopes } from "@nodefony/ai";
 // nodefony/service/DevkitService.ts
@@ -144,9 +144,9 @@ let DevkitService = class DevkitService extends Service {
 			servesTraffic: () => kernel?.runProfile.servers === true,
 			onShutdown: (listener) => {
 				if (kernel === null) return () => {};
-				kernel.prependOnceListener("onTerminate", listener);
+				kernel.once("onDrain", listener);
 				return () => {
-					kernel.removeListener("onTerminate", listener);
+					kernel.removeListener("onDrain", listener);
 				};
 			},
 			profileRoute: {

package/docs/index.md

@@ -477,7 +477,7 @@ agent invente : faute d'une marche à suivre, il écrit un CRUD à la main, un
 service à méthodes `static` que le conteneur ne voit pas, un contrôle de droits
 dans le corps de l'action.
 
-Le paquet livre donc onze **skills** au format [Agent Skills](https://agentskills.io) :
+Le paquet livre donc douze **skills** au format [Agent Skills](https://agentskills.io) :
 un qui porte la conduite commune de toute tâche, un qui part du symptôme d'une panne,
 et un par geste où l'invention coûte cher :
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nodefony/devkit",
-  "version": "10.0.0-beta.5",
+  "version": "10.0.0-beta.7",
   "type": "module",
   "description": "Outillage de développement d'une application Nodefony : carte de visite du projet et portes de découverte pour un agent de développement",
   "author": "Christophe CAMENSULI <ccamensuli@gmail.com>",
@@ -27,24 +27,24 @@
     "test:integration": "vitest run --config vitest.integration.config.ts"
   },
   "peerDependencies": {
-    "@nodefony/ai": "^10.0.0-beta.5",
-    "@nodefony/framework": "^10.0.0-beta.5",
-    "@nodefony/http": "^10.0.0-beta.5",
-    "lighthouse": "^13.0.0",
-    "nodefony": "^10.0.0-beta.5",
+    "@nodefony/ai": "^10.0.0-beta.7",
+    "@nodefony/framework": "^10.0.0-beta.7",
+    "@nodefony/http": "^10.0.0-beta.7",
+    "lighthouse": "^13.6.0",
+    "nodefony": "^10.0.0-beta.7",
     "playwright": "^1.50.0",
     "zod": "^4.6.7"
   },
   "devDependencies": {
     "@modelcontextprotocol/sdk": "1.32.2",
-    "@nodefony/ai": "^10.0.0-beta.5",
-    "@nodefony/framework": "^10.0.0-beta.5",
-    "@nodefony/http": "^10.0.0-beta.5",
-    "nodefony": "^10.0.0-beta.5"
+    "@nodefony/ai": "^10.0.0-beta.7",
+    "@nodefony/framework": "^10.0.0-beta.7",
+    "@nodefony/http": "^10.0.0-beta.7",
+    "nodefony": "^10.0.0-beta.7"
   },
   "dependencies": {
     "axe-core": "4.14.0",
-    "tslib": "2.8.1"
+    "tslib": "2.9.1"
   },
   "peerDependenciesMeta": {
     "playwright": {
@@ -59,7 +59,7 @@
     "url": "git+https://github.com/nodefony/nodefony-core.git",
     "directory": "src/packages/@nodefony/devkit"
   },
-  "homepage": "https://nodefony.github.io/nodefony-core/",
+  "homepage": "https://nodefony.net/",
   "bugs": {
     "url": "https://github.com/nodefony/nodefony-core/issues"
   },
@@ -77,6 +77,6 @@
     "esm"
   ],
   "engines": {
-    "node": ">=24.14.0"
+    "node": "^24.16.0 || >=26.0.0"
   }
 }

package/skills/nodefony-add-crud/SKILL.md

@@ -32,7 +32,7 @@ description: >
 ## Le geste
 
 ```bash
-npx nodefony create entity Article title:string body:text? published:bool
+npx nodefony create entity Article title:string "body:text?" published:bool
 ```
 
 Une seule commande produit la chaîne entière : la table, son interface de ligne, les schémas de
@@ -57,24 +57,25 @@ fixe un défaut LITTÉRAL, `:unique` pose une contrainte d'unicité, `:index` un
 camelCase (`publishedAt`). Une faute de casse ou un type d'un autre outil (`boolean`, `integer`)
 est refusé avec la forme juste proposée.
 
-| Type           | Ce que ça produit             | SQLite          | PostgreSQL       | MySQL / MariaDB | MongoDB                |
-| -------------- | ----------------------------- | --------------- | ---------------- | --------------- | ---------------------- |
-| `string(n)`    | texte court, borné (255)      | `text` ¹        | `varchar(n)`     | `varchar(n)`    | `String` + `maxlength` |
-| `text`         | texte long                    | `text`          | `text`           | `text`          | `String`               |
-| `int`          | entier                        | `integer`       | `integer`        | `int`           | `Number`               |
-| `float`        | nombre à virgule              | `real`          | `double`         | `double`        | `Number`               |
-| `decimal(p,s)` | décimal EXACT (voyage chaîne) | `numeric`       | `numeric(p,s)`   | `decimal(p,s)`  | `String`               |
-| `bool`         | booléen                       | `integer` (0/1) | `boolean`        | `boolean`       | `Boolean`              |
-| `json`         | document libre                | `text` (JSON)   | `jsonb`          | `json`          | `Mixed`                |
-| `date`         | horodatage (ms)               | `integer` (ms)  | `timestamptz(3)` | `datetime(3)`   | `Date`                 |
-| `uuid`         | identifiant                   | `text`          | `uuid`           | `varchar(36)`   | `String`               |
-| `char(n)`      | longueur EXACTE               | `text` ¹        | `char(n)`        | `char(n)`       | `String`, `n` exact    |
-| `enum(a,b)`    | valeurs admises ²             | `text`          | `varchar(255)`   | `varchar(255)`  | `String` + `enum`      |
-| `ref:<Entité>` | relation ³                    | clé étrangère   | clé étrangère    | clé étrangère   | `ObjectId` + `ref`     |
-
-¹ SQLite n'applique aucune longueur : c'est le schéma d'entrée (Zod) qui borne, sur TOUS les
-transports. ² Même colonne partout, sans type SQL nommé (qui exigerait une migration) : le type
-TypeScript et le schéma Zod bornent les valeurs. ³ En SQL, la colonne prend le type de la clé
+| Type           | Ce que ça produit             | SQLite              | PostgreSQL         | MySQL / MariaDB       | MongoDB                |
+| -------------- | ----------------------------- | ------------------- | ------------------ | --------------------- | ---------------------- |
+| `string(n)`    | texte court, borné (255)      | `text(n)` + CHECK ¹ | `varchar(n)`       | `varchar(n)`          | `String` + `maxlength` |
+| `text`         | texte long                    | `text`              | `text`             | `text`                | `String`               |
+| `int`          | entier                        | `integer`           | `integer`          | `int`                 | `Number`               |
+| `float`        | nombre à virgule              | `real`              | `double precision` | `double`              | `Number`               |
+| `decimal(p,s)` | décimal EXACT (voyage chaîne) | `text`              | `numeric(p,s)`     | `decimal(p,s)`        | `String`               |
+| `bool`         | booléen                       | `integer` (0/1)     | `boolean`          | `boolean`             | `Boolean`              |
+| `json`         | document libre                | `text` (JSON)       | `jsonb`            | `json`                | `Mixed`                |
+| `date`         | horodatage (ms)               | `integer` (ms)      | `timestamptz(3)`   | `datetime(3)`         | `Date`                 |
+| `uuid`         | identifiant                   | `text`              | `uuid`             | `varchar(36)`         | `String`               |
+| `char(n)`      | longueur EXACTE               | `text` + CHECK ¹    | `char(n)` + CHECK  | `char(n)` + CHECK     | `String`, `n` exact    |
+| `enum(a,b)`    | valeurs admises ²             | `text` + CHECK      | `text` + CHECK     | `varchar(64)` + CHECK | `String` + `enum`      |
+| `ref:<Entité>` | relation ³                    | clé étrangère       | clé étrangère      | clé étrangère         | `ObjectId` + `ref`     |
+
+¹ SQLite ne borne pas un `text` : une contrainte `CHECK` sur la longueur le fait en base, et le
+schéma d'entrée (Zod) avant elle, sur TOUS les transports. ² Aucun type `ENUM` SQL : une colonne
+texte et une contrainte `CHECK` qui liste les valeurs, chacune de 64 caractères au plus ; le type
+TypeScript et le schéma Zod bornent avant la base. ³ En SQL, la colonne prend le type de la clé
 visée (`uuid`, entier pour `--id serial`, texte pour `User`) ; en MongoDB, aucune clé étrangère.
 
 La table exacte, par moteur, telle que CETTE version l'écrit :
@@ -108,7 +109,7 @@ tests — sans table ni migration (la collection naît à la première écriture
 les options qui ont un sens ici :
 
 ```bash
-npx nodefony create entity Post title:string(120) body:text? views:int=0 status:enum(draft,published)=draft slug:string:unique tags:json? author:ref:User --soft-delete --route /api/posts --dry-run
+npx nodefony create entity Post "title:string(120)" "body:text?" views:int=0 "status:enum(draft,published)=draft" slug:string:unique "tags:json?" author:ref:User --soft-delete --route /api/posts --dry-run
 ```
 
 - La clé est l'`_id` natif, servie en `id` ; `ref:<Entité>` est un `ObjectId` indexé, chargé
@@ -121,6 +122,17 @@ npx nodefony create entity Post title:string(120) body:text? views:int=0 status:
   `--id`, `--index`, `--unique`. Un index composite s'écrit à la main dans le schéma.
 - `User` ne se régénère pas : il s'étend dans `nodefony/entity/User.ts` (son TSDoc donne le geste).
 
+## Le graphe d'entités de la console
+
+Les liens du graphe viennent des `ref:` eux-mêmes : la clé étrangère que la base porte devient
+une arête, sans rien répéter ailleurs. Le regroupement et la couleur suivent le **domaine** de
+l'entité, sinon son module — et une application de centaines de tables tient souvent dans UN
+module :
+
+```bash
+npx nodefony create entity Invoice "number:string(30):unique" "total:decimal(24,8)" customer:ref:Customer --domain facturation --dry-run
+```
+
 ## Épouser une table qui existe déjà
 
 Trois réglages, et ils ne touchent **que** le SQL — la propriété TypeScript reste `id`, `siteId` :
@@ -200,8 +212,11 @@ refus tombe tout seul.
    `--no-migrate` s'en dispense ; si des entités modifiées attendaient, la migration est écrite mais
    PAS appliquée, et la sortie nomme les tables en trop. Sinon, la table naît au prochain démarrage
    en développement (`CREATE TABLE IF NOT EXISTS`).
-2. **La modifier n'altère rien** — aucun `ALTER` n'est émis. Une colonne ajoutée à une entité déjà
-   créée n'apparaîtra pas dans une base existante.
+2. **La modifier passe par une migration** dès que l'application versionne ses migrations :
+   `npx nodefony orm:generate --name <nom> --apply` (skill **`nodefony-migrate-schema`**). Sans
+   migrations versionnées, le démarrage en développement rattrape seul une colonne ajoutée qui
+   **accepte le vide** (`ADD COLUMN`, annoncé) ; une colonne **obligatoire** ne l'est jamais — le
+   démarrage nomme l'écart au lieu d'inventer la valeur des lignes existantes.
 3. **La production ne fabrique JAMAIS le schéma.** Elle l'applique par des migrations, écrites par
    `npx nodefony orm:generate` et posées par `npx nodefony orm:migrate` — c'est un geste à part,
    avec ses refus et ses interdits : skill **`nodefony-migrate-schema`**.
@@ -218,7 +233,7 @@ geste :
 - **nom réservé par un module du framework** (`session`, `access_token`, `audit_event`…) — un
   homonyme dépossède le module, et l'application ne démarre plus sur un message parlant d'une
   colonne inconnue. **`User` fait exception** : l'identité appartient à l'application, et
-  `create entity User firstName:string(100)?` écrit l'entité avec les colonnes du contrat plus
+  `create entity User "firstName:string(100)?"` écrit l'entité avec les colonnes du contrat plus
   les tiennes. Trois refus s'y appliquent alors — renommer la table ou changer la casse des
   colonnes (des requêtes les écrivent en dur), la poser ailleurs que dans l'application racine
   (l'ordre de chargement n'y est pas garanti), et déclarer un champ obligatoire **sans valeur par

package/skills/nodefony-add-grpc-service/SKILL.md

@@ -0,0 +1,179 @@
+---
+name: nodefony-add-grpc-service
+metadata:
+  version: 1.0.0
+description: >
+  Sert un service gRPC dans une application Nodefony — contrat `.proto`, code généré par `buf`,
+  contrôleur `GrpcController` marqué `@GrpcService`, déclaré par `@controllers` — à charger AVANT
+  d'écrire le contrat ou le contrôleur. Porte les paquets à installer, les pièges de génération,
+  ce que le framework décide à ta place (ports, refus 16/7, erreurs, arrêt, tailles) et un
+  script qui appelle la méthode depuis n'importe quel système pour prouver qu'elle répond.
+  Déclencheurs : "service gRPC", "exposer un contrat protobuf", "un client Go doit appeler
+  l'application", "gRPC-Web", "Connect", "buf generate", "@GrpcService", "GrpcController",
+  "appeler une méthode gRPC", "UNAUTHENTICATED", "UNIMPLEMENTED", "flux gRPC".
+---
+
+# add-grpc-service — un contrat typé, servi par le pipeline
+
+> 🧭 **Tu es arrivé ici directement ? Charge aussi `nodefony-dev`** — il porte la conduite
+> commune (par où commencer, comment prouver que c'est fait). Cette page-ci ne couvre QUE gRPC.
+>
+> La référence complète est INSTALLÉE : `node_modules/@nodefony/framework/docs/grpc.md` (le
+> pourquoi de chaque choix, les tables de codes, les limites). Une commande la retrouve, ligne
+> comprise :
+> `node node_modules/@nodefony/devkit/skills/nodefony-dev/scripts/docs.mjs grpc`.
+
+> ⚖️ **La confiance n'exclut pas le contrôle.** Un contrôleur qui compile n'est pas un service
+> qui répond. Le juge est l'appel réel (§ Prouver).
+
+## Ce qu'il faut savoir avant d'écrire
+
+- **Une méthode gRPC est une route.** Le pare-feu, `@IsGranted`, l'identité (`this.user`) et le
+  journal valent comme sur toute route. N'ouvre JAMAIS un second serveur (`@grpc/grpc-js` et son
+  `bindAsync`) : il contournerait le pare-feu et les droits.
+- **Trois protocoles, servis d'office** : gRPC (HTTP/2 seulement : port 5152 en TLS), gRPC-Web et
+  Connect (aussi en HTTP/1.1 : port 5151). Un navigateur et `curl` passent par Connect.
+- **Surface expérimentale** : sa forme peut changer en version mineure, toujours annoncée.
+
+## Le geste
+
+### 1. Les paquets
+
+```bash
+npm i @connectrpc/connect @connectrpc/connect-node @bufbuild/protobuf
+npm i -D @bufbuild/buf @bufbuild/protoc-gen-es
+```
+
+Le runtime en `dependencies` (une installation de production doit l'avoir), le générateur en
+développement. Si npm annonce que le script d'installation de `@bufbuild/buf` est bloqué
+(`allowScripts`), ce n'est pas un échec : `buf` fonctionne sans.
+
+### 2. Le contrat — `proto/<paquet>/v1/<nom>.proto`
+
+```proto
+edition = "2024";
+
+package greet.v1;
+
+service GreetService {
+  rpc Greet(GreetRequest) returns (GreetResponse);
+}
+
+message GreetRequest {
+  string name = 1;
+}
+
+message GreetResponse {
+  string greeting = 1;
+}
+```
+
+Le dossier suit le paquet (`greet/v1/` pour `greet.v1`) : c'est ce que vérifie `buf lint`.
+
+### 3. La génération — deux fichiers à la racine, à côté de `proto/`
+
+```yaml
+# buf.yaml
+version: v2
+modules:
+  - path: proto
+lint:
+  use: [STANDARD]
+breaking:
+  use: [FILE]
+```
+
+```yaml
+# buf.gen.yaml
+version: v2
+inputs:
+  - directory: proto
+plugins:
+  - local: protoc-gen-es
+    out: nodefony/gen
+    opt: target=ts
+```
+
+```bash
+npx buf lint
+npx buf generate
+```
+
+`nodefony/gen/greet/v1/greet_pb.ts` est **commité** et jamais édité : régénérer après chaque
+changement du contrat. Nodefony ne génère rien au build ni au démarrage.
+
+### 4. Le contrôleur — `nodefony/controllers/GreetController.ts`
+
+```ts
+import { GrpcController, GrpcService } from "@nodefony/framework/grpc";
+import type { ContextType } from "@nodefony/http";
+import { GreetService } from "../gen/greet/v1/greet_pb";
+import type { GreetRequest } from "../gen/greet/v1/greet_pb";
+
+@GrpcService(GreetService)
+export class GreetController extends GrpcController {
+  constructor(context: ContextType) {
+    super("GreetController", context);
+  }
+
+  greet(request: GreetRequest) {
+    return { greeting: `Bonjour, ${request.name} !` };
+  }
+}
+```
+
+Une méthode par méthode du contrat, nom en minuscule initiale (`Greet` → `greet`). Une méthode
+manquante ou mal typée ne compile pas. La logique métier va dans un service injecté
+(`@Inject("nom")` au constructeur — skill `nodefony-add-service`).
+
+### 5. La déclaration — `index.ts` de l'application
+
+Ajouter la classe à la liste existante : `@controllers([HomeController, GreetController])`.
+Sans cela, la classe compile et aucune route n'existe.
+
+## Ce que le framework décide pour toi
+
+| Sujet            | Ce qui se passe                                                                                             | Ton geste                                          |
+| ---------------- | ----------------------------------------------------------------------------------------------------------- | -------------------------------------------------- |
+| Droits           | `@IsGranted` sur la méthode ; refus sans identité → 16 `UNAUTHENTICATED`, identifié → 7 `PERMISSION_DENIED` | rien : ne traduis pas toi-même                     |
+| Erreurs          | `ConnectError` part telle quelle ; `HttpError` traduite ; toute autre exception → 13 `INTERNAL`             | lever `new ConnectError(msg, Code.X)` pour choisir |
+| Flux             | traduction des erreurs avant le premier message seulement ; arrêt du serveur → 14 ; identité révoquée → 16  | passer `ctx.signal` à tes sources                  |
+| Tailles          | 4 Mio par message, reçu ou émis                                                                             | section `grpc` de la config http pour changer      |
+| Échéance         | unaire : la plus courte du client et du serveur → 4 ; flux : aucune                                         | rien                                               |
+| Décorateurs HTTP | `@Body`, `@UseSession`, `@Csp`, `@Idempotent`… sur une méthode du contrat ARRÊTENT le démarrage             | les retirer : le message EST le paramètre          |
+
+## Prouver
+
+Application démarrée (`npx nodefony development`) :
+
+```bash
+npx nodefony inspect routes --json
+node node_modules/@nodefony/devkit/skills/nodefony-add-grpc-service/scripts/call.mjs greet.v1.GreetService/Greet --field name=Ada
+```
+
+- `inspect routes` doit montrer `POST /greet.v1.GreetService/Greet`. Absente : la classe n'est
+  pas dans `@controllers`, ou le `dist` est périmé.
+- `call.mjs` rend `HTTP 200` et le message — ou le code gRPC d'un refus (`unauthenticated`…).
+  Il passe sous Windows, sans `curl` ni guillemets imbriqués. Message riche : `--file message.json`.
+  Jeton : `--header authorization=Bearer <jeton>`. Codes de sortie : 0 réponse, 1 refus,
+  64 mauvais usage, 69 application injoignable.
+- `npm run typecheck` ne prouve que la forme ; seul l'appel prouve le service.
+
+## Pièges
+
+| Symptôme                                                      | Cause                                                                | Geste                                                                            |
+| ------------------------------------------------------------- | -------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
+| `Cannot find package '@connectrpc/connect-node'` au démarrage | paquet non installé                                                  | `npm i @connectrpc/connect @connectrpc/connect-node @bufbuild/protobuf`          |
+| `buf generate` : `protoc-gen-es` introuvable                  | lancé hors de l'application, ou générateur non installé              | le lancer à la racine de l'application, après `npm i -D @bufbuild/protoc-gen-es` |
+| Un client gRPC natif échoue tout de suite en `INTERNAL`       | il vise 5151, qui est en HTTP/1.1                                    | viser 5152 (TLS)                                                                 |
+| `unimplemented` sur un chemin qui semble juste                | casse ou paquet faux dans le chemin (`/greet.v1.GreetService/Greet`) | recopier le chemin depuis `inspect routes`                                       |
+| La méthode tourne encore après l'arrêt                        | elle n'écoute pas `ctx.signal`                                       | le passer à la base, à l'abonnement, à `fetch`                                   |
+
+## Voisins
+
+| Besoin                                | Skill                           |
+| ------------------------------------- | ------------------------------- |
+| La logique métier du service          | `nodefony-add-service`          |
+| Réserver une méthode à un rôle        | `nodefony-protect-route`        |
+| Un flux temps réel vers le navigateur | `nodefony-add-realtime-channel` |
+| Le service ne démarre pas             | `nodefony-troubleshoot`         |