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

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

@@ -1,4 +1,4 @@
-// \0@oxc-project+runtime@0.157.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.157.0 → _@oxc-project_runtime@0.158.0}/helpers/esm/decorateParam.js

@@ -1,4 +1,4 @@
-// \0@oxc-project+runtime@0.157.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

@@ -4,7 +4,7 @@ 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.157.0/helpers/esm/decorate.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";

package/dist/nodefony/controllers/DevkitController.js

@@ -1,4 +1,4 @@
-import __decorate from "../../_virtual/_@oxc-project_runtime@0.157.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 __decorateParam from "../../_virtual/_@oxc-project_runtime@0.157.0/helpers/esm/decorateParam.js";
-import __decorate from "../../_virtual/_@oxc-project_runtime@0.157.0/helpers/esm/decorate.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.157.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/service/DevkitService.js

@@ -4,7 +4,7 @@ import { PROFILE_SESSION_FACTOR } from "../src/profileSession.js";
 import { readShotTarget } from "../mcp/shotClient.js";
 import { buildCard } from "../src/card.js";
 import defaults from "../config/config.js";
-import __decorate from "../../_virtual/_@oxc-project_runtime@0.157.0/helpers/esm/decorate.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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nodefony/devkit",
-  "version": "10.0.0-beta.6",
+  "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,20 +27,20 @@
     "test:integration": "vitest run --config vitest.integration.config.ts"
   },
   "peerDependencies": {
-    "@nodefony/ai": "^10.0.0-beta.6",
-    "@nodefony/framework": "^10.0.0-beta.6",
-    "@nodefony/http": "^10.0.0-beta.6",
+    "@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.6",
+    "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.6",
-    "@nodefony/framework": "^10.0.0-beta.6",
-    "@nodefony/http": "^10.0.0-beta.6",
-    "nodefony": "^10.0.0-beta.6"
+    "@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",
@@ -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-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`         |

package/skills/nodefony-add-grpc-service/scripts/call.mjs

@@ -0,0 +1,218 @@
+#!/usr/bin/env node
+/**
+ * Appelle une méthode gRPC d'une application Nodefony, en protocole Connect
+ * (JSON sur HTTP) — la preuve qu'un service répond, sans `curl` ni guillemets.
+ *
+ * `curl -d '{"name":"Ada"}'` ne passe ni dans cmd.exe ni dans Windows PowerShell,
+ * et `grpcurl` n'est pas installé partout. Ce script n'emploie que `fetch` de
+ * Node : il marche à l'identique sur les trois plateformes, et il rend le CODE
+ * gRPC du refus (`unauthenticated`, `permission_denied`…), pas seulement un
+ * statut HTTP.
+ *
+ * `@usage` node node_modules/@nodefony/devkit/skills/nodefony-add-grpc-service/scripts/call.mjs greet.v1.GreetService/Greet --field name=Ada
+ * `@usage` node node_modules/@nodefony/devkit/skills/nodefony-add-grpc-service/scripts/call.mjs greet.v1.GreetService/Greet --file body.json
+ * `@option` --field - un champ du message, `nom=valeur` (répétable ; la valeur est une chaîne)
+ * `@option` --file - le message entier, lu dans un fichier JSON
+ * `@option` --header - un en-tête, `nom=valeur` (répétable), par exemple `authorization=Bearer …`
+ * `@option` --url - l'adresse de l'application (défaut http://127.0.0.1:5151)
+ * `@option` --json - la réponse brute, sérialisée, pour rechaîner
+ * `@requires` l'application démarrée
+ * `@output` le statut HTTP, puis le message reçu ou le code gRPC du refus
+ */
+
+import { readFileSync, realpathSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+
+/** L'adresse d'une application de développement, sans TLS. */
+const DEFAULT_URL = "http://127.0.0.1:5151";
+
+/** Une méthode gRPC : `paquet.Service/Méthode`, sans barre de tête. */
+const METHOD_RE = /^[A-Za-z_][\w.]*\.[A-Za-z_]\w*\/[A-Za-z_]\w*$/u;
+
+const USAGE = `
+Appelle une méthode gRPC d'une application Nodefony, en Connect (JSON sur HTTP).
+
+  call.mjs <paquet.Service/Méthode> [--field nom=valeur]...   le message, champ par champ
+  call.mjs <paquet.Service/Méthode> --file message.json       le message, depuis un fichier
+  call.mjs ... --header authorization=Bearer <jeton>          un en-tête (répétable)
+  call.mjs ... --url http://127.0.0.1:5151                    l'application visée
+  call.mjs ... --json                                         la réponse brute
+
+Codes de sortie : 0 réponse · 1 refus ou erreur gRPC · 64 mauvais usage · 69 application injoignable
+`.trim();
+
+/**
+ * Coupe `nom=valeur` au PREMIER `=` : une valeur peut en contenir (jeton base64).
+ *
+ * @param {string} pair - la paire saisie.
+ * @returns {[string, string] | null} le nom et la valeur, ou `null` si la forme est fausse.
+ */
+const splitPair = (pair) => {
+  const at = pair.indexOf("=");
+  if (at <= 0) return null;
+  return [pair.slice(0, at), pair.slice(at + 1)];
+};
+
+/**
+ * Lit la ligne de commande.
+ *
+ * @param {string[]} argv - les arguments, sans `node` ni le script.
+ * @returns {{ method: string, url: string, body: Record<string, unknown>, headers: Record<string, string>, json: boolean } | { error: string }}
+ *   la demande, ou l'erreur d'usage à afficher.
+ */
+export function parseArgs(argv) {
+  let method = null;
+  let url = DEFAULT_URL;
+  let json = false;
+  let file = null;
+  const fields = Object.create(null);
+  const headers = Object.create(null);
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === "--json") {
+      json = true;
+      continue;
+    }
+    if (
+      arg === "--field" ||
+      arg === "--header" ||
+      arg === "--url" ||
+      arg === "--file"
+    ) {
+      const value = argv[++i];
+      if (value === undefined) return { error: `${arg} attend une valeur` };
+      if (arg === "--url") url = value;
+      else if (arg === "--file") file = value;
+      else {
+        const pair = splitPair(value);
+        if (pair === null)
+          return { error: `${arg} attend nom=valeur, reçu « ${value} »` };
+        (arg === "--field" ? fields : headers)[pair[0]] = pair[1];
+      }
+      continue;
+    }
+    if (arg.startsWith("-")) return { error: `option inconnue : ${arg}` };
+    if (method !== null)
+      return { error: `une seule méthode par appel (reçu « ${arg} »)` };
+    method = arg.replace(/^\/+/u, "");
+  }
+  if (method === null) return { error: "la méthode à appeler manque" };
+  if (!METHOD_RE.test(method)) {
+    return {
+      error: `méthode « ${method} » : la forme est paquet.Service/Méthode, comme greet.v1.GreetService/Greet`,
+    };
+  }
+  let body = fields;
+  if (file !== null) {
+    if (Object.keys(fields).length !== 0)
+      return { error: "--file et --field s'excluent" };
+    try {
+      body = JSON.parse(readFileSync(file, "utf8"));
+    } catch (e) {
+      return {
+        error: `--file ${file} : ${e instanceof Error ? e.message : String(e)}`,
+      };
+    }
+  }
+  return { method, url: url.replace(/\/+$/u, ""), body, headers, json };
+}
+
+/**
+ * Envoie l'appel Connect unaire et lit la réponse.
+ *
+ * @param {{ method: string, url: string, body: unknown, headers: Record<string, string> }} request - la demande.
+ * @returns {Promise<{ status: number, payload: unknown }>} le statut HTTP et le corps décodé (texte brut s'il n'est pas JSON).
+ */
+export async function callConnect(request) {
+  const response = await fetch(`${request.url}/${request.method}`, {
+    method: "POST",
+    headers: {
+      ...request.headers,
+      "content-type": "application/json",
+      "connect-protocol-version": "1",
+    },
+    body: JSON.stringify(request.body),
+  });
+  const text = await response.text();
+  let payload = text;
+  try {
+    payload = text === "" ? {} : JSON.parse(text);
+  } catch {
+    // corps non JSON (une page d'erreur HTML) : rendu tel quel
+  }
+  return { status: response.status, payload };
+}
+
+/**
+ * Le code gRPC d'un refus Connect (`{"code":"unauthenticated"}`), ou `null`.
+ *
+ * @param {unknown} payload - le corps décodé.
+ * @returns {string | null} le code textuel.
+ */
+const connectCode = (payload) =>
+  payload !== null &&
+  typeof payload === "object" &&
+  "code" in payload &&
+  typeof payload.code === "string"
+    ? payload.code
+    : null;
+
+/**
+ * Exécute la commande.
+ *
+ * @param {string[]} argv - les arguments.
+ * @returns {Promise<number>} le code de sortie.
+ */
+export async function main(argv) {
+  const request = parseArgs(argv);
+  if ("error" in request) {
+    process.stderr.write(`${request.error}\n\n${USAGE}\n`);
+    return 64;
+  }
+  let result;
+  try {
+    result = await callConnect(request);
+  } catch (e) {
+    const cause =
+      e instanceof Error && e.cause instanceof Error
+        ? e.cause.message
+        : String(e);
+    process.stderr.write(
+      `L'application ne répond pas sur ${request.url} (${cause}).\n` +
+        "Démarre-la : npx nodefony development — puis relance l'appel.\n",
+    );
+    return 69;
+  }
+  const { status, payload } = result;
+  if (request.json) {
+    process.stdout.write(`${JSON.stringify({ status, payload })}\n`);
+  } else if (status === 200) {
+    process.stdout.write(
+      `HTTP 200 · ${request.method}\n${JSON.stringify(payload, null, 2)}\n`,
+    );
+  } else {
+    const code = connectCode(payload);
+    process.stdout.write(
+      code === null
+        ? `HTTP ${status} · ${request.method} — pas une réponse gRPC :\n${typeof payload === "string" ? payload : JSON.stringify(payload, null, 2)}\n`
+        : `HTTP ${status} · ${request.method} — refus gRPC « ${code} »${
+            typeof payload === "object" &&
+            payload !== null &&
+            "message" in payload
+              ? ` : ${String(payload.message)}`
+              : ""
+          }\n`,
+    );
+  }
+  return status === 200 ? 0 : 1;
+}
+
+// Exécuté directement (et non importé par son test) : rendre le code. Chemins
+// RÉELS des deux côtés — lancé par un lien (`/var/…` sous macOS), la
+// comparaison brute échouait et le script ne faisait rien.
+if (
+  process.argv[1] !== undefined &&
+  realpathSync(process.argv[1]) === fileURLToPath(import.meta.url)
+) {
+  process.exitCode = await main(process.argv.slice(2));
+}