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

package/skills/nodefony-troubleshoot/scripts/log-errors.mjs

@@ -0,0 +1,465 @@
+#!/usr/bin/env node
+/**
+ * Extrait les erreurs du journal d'une application Nodefony — regroupées, datées, avec le geste qui suit.
+ *
+ * Un journal de développement fait vite des milliers de lignes, dont l'immense
+ * majorité dit que tout va bien. Le lire en entier noie l'erreur ; le couper
+ * (`tail`) la coupe aussi, sans le dire. Ce script lit TOUT, ne garde que les
+ * sévérités qui comptent, recolle une pile d'appels à la ligne qui l'a levée,
+ * fusionne les répétitions, et nomme le premier geste quand il le connaît.
+ *
+ * Il lit les deux formes que le framework écrit dans `logs/` : le texte
+ * (`nodefony-detached.log` d'un serveur lancé avec `--detach`, `nodefony-<pid>.log`
+ * du pilote fichier, ou tout fichier où tu as redirigé la sortie) et le JSON par
+ * ligne (`nodefony-<pid>.jsonl`). Un plantage brut de Node — `SyntaxError: …`
+ * hors du format du journal — est reconnu aussi.
+ *
+ * `@usage` node node_modules/@nodefony/devkit/skills/nodefony-troubleshoot/scripts/log-errors.mjs
+ * `@usage` node node_modules/@nodefony/devkit/skills/nodefony-troubleshoot/scripts/log-errors.mjs logs/dev.log
+ * `@usage` node node_modules/@nodefony/devkit/skills/nodefony-troubleshoot/scripts/log-errors.mjs --warnings --last 40
+ * `@option` --warnings - garde aussi les avertissements (WARNING)
+ * `@option` --last - nombre d'erreurs distinctes rendues, les plus récentes (défaut 15)
+ * `@option` --json - la même réponse, sérialisée, pour rechaîner
+ * `@option` --root - racine du projet (défaut : le dossier courant)
+ * `@output` les erreurs distinctes, de la plus ancienne à la plus récente, avec fichier, heure, nombre et piste
+ *
+ * Sorties : `0` aucune erreur · `1` au moins une erreur · `64` usage · `66` aucun journal lisible.
+ */
+
+import {
+  readFileSync,
+  readdirSync,
+  statSync,
+  openSync,
+  fstatSync,
+  readSync,
+  closeSync,
+  realpathSync,
+} from "node:fs";
+import path from "node:path";
+import process from "node:process";
+import { fileURLToPath } from "node:url";
+import { findProjectRoot } from "nodefony/project-root";
+
+/**
+ * Racine de l'APPLICATION vue depuis `cwd` — le dossier qui porte
+ * `nodefony.config.ts` —, ou `cwd` lui-même hors application. Un script lancé
+ * depuis `frontend/` ou `modules/blog/` travaille ainsi sur l'app entière.
+ * `nodefony/project-root` est le sous-chemin LÉGER du cœur (`node:` seul) :
+ * importer `nodefony` entier coûtait jusqu'à plusieurs secondes à froid.
+ *
+ * @param {string} cwd - le dossier de lancement.
+ * @returns {string} la racine retenue.
+ */
+const appRoot = (cwd) => findProjectRoot(cwd) ?? cwd;
+
+/** Erreurs distinctes rendues par défaut — au-delà, personne ne lit. */
+const DEFAULT_LAST = 15;
+
+/** Octets relus depuis la FIN d'un journal : un journal de plusieurs Go ne doit pas saturer la mémoire. */
+const MAX_SCAN_BYTES = 8 * 1024 * 1024;
+
+/** Sévérités du journal (RFC 5424), de la plus grave à la plus anodine. */
+const SEVERITY = {
+  EMERGENCY: 0,
+  ALERT: 1,
+  CRITIC: 2,
+  ERROR: 3,
+  WARNING: 4,
+  NOTICE: 5,
+  INFO: 6,
+  DEBUG: 7,
+};
+
+/** Codes ANSI de couleur : le journal texte en porte quand il est écrit pour un terminal. */
+const ANSI = /\u001b\[[0-9;]*m/gu;
+
+/** Une ligne du journal texte : `HH:MM:SS.mmm SÉVÉRITÉ MSGID : message`. */
+const PDU_LINE =
+  /^(\d{2}:\d{2}:\d{2}\.\d{3})\s+(EMERGENCY|ALERT|CRITIC|ERROR|WARNING|NOTICE|INFO|DEBUG)\s+(.+?)\s+:\s?(.*)$/u;
+
+/** Une erreur levée HORS du journal — le plantage brut que Node écrit lui-même. */
+const RAW_ERROR =
+  /^(?:Uncaught )?((?:[A-Z][A-Za-z]*)?Error)(?: \[[A-Z_]+\])?: (.+)$/u;
+
+/** Une ligne de pile d'appels, rattachée à l'erreur qui la précède. */
+const STACK_LINE = /^\s+at\s/u;
+
+/**
+ * Ce que le message dit, et le premier geste qui en découle.
+ *
+ * Seulement des causes ÉTABLIES : une piste fausse coûte plus qu'aucune piste,
+ * parce qu'on la suit. Ce qui n'est pas ici se lit dans le message lui-même.
+ */
+const HINTS = [
+  {
+    when: /does not provide an export named/u,
+    hint: "un `dist/` en retard sur les sources, ou deux copies de `nodefony` : `npm run build`, puis `npm ls nodefony`",
+  },
+  {
+    when: /Cannot find (?:module|package)|ERR_MODULE_NOT_FOUND/u,
+    hint: "dépendance ou build manquant : `npm install`, puis `npm run build`",
+  },
+  {
+    when: /BootConfigurationError/u,
+    hint: "configuration refusée au démarrage (sortie 78) : le message NOMME la clé — corrige-la, ne la retire pas",
+  },
+  {
+    when: /EADDRINUSE|already in use/u,
+    hint: "port déjà tenu : `npx nodefony status` nomme qui le tient (une ligne « retrying » juste après = rattrapé seul)",
+  },
+  {
+    when: /no such table|no such column|does not exist|doesn't exist|Unknown column|migrations? à appliquer/u,
+    hint: "schéma de base en retard sur les entités : skill `nodefony-migrate-schema`",
+  },
+  {
+    when: /ECONNREFUSED|ENOTFOUND|getaddrinfo/u,
+    hint: "un service extérieur (base, cache, fournisseur) ne répond pas : `npx nodefony doctor --live`",
+  },
+  {
+    when: /^SIG(?:TERM|INT|HUP)$/u,
+    hint: "arrêt DEMANDÉ au processus — pas une panne",
+  },
+];
+
+const FLAGS = new Set([
+  "--warnings",
+  "--last",
+  "--json",
+  "--root",
+  "--help",
+  "-h",
+]);
+
+/**
+ * Lit les arguments, et REFUSE ce qu'il ne comprend pas.
+ *
+ * Un drapeau mal tapé qu'on ignorerait rendrait « aucune erreur » — la pire
+ * réponse possible d'un outil de dépannage.
+ *
+ * @param argv - les arguments, sans `node` ni le chemin du script.
+ * @returns les options lues.
+ * @throws Error quand un drapeau est inconnu ou qu'une valeur manque.
+ */
+export function parseArgs(argv, cwd = process.cwd()) {
+  const opts = {
+    files: [],
+    warnings: false,
+    last: DEFAULT_LAST,
+    json: false,
+    root: appRoot(cwd),
+    help: false,
+  };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (!a.startsWith("-")) {
+      opts.files.push(a);
+      continue;
+    }
+    if (!FLAGS.has(a)) throw new Error(`option inconnue : ${a}`);
+    if (a === "--help" || a === "-h") opts.help = true;
+    else if (a === "--warnings") opts.warnings = true;
+    else if (a === "--json") opts.json = true;
+    else {
+      const v = argv[++i];
+      if (v === undefined || v.startsWith("-"))
+        throw new Error(`${a} attend une valeur`);
+      if (a === "--root") opts.root = path.resolve(v);
+      else {
+        const n = Number(v);
+        if (!Number.isInteger(n) || n < 1)
+          throw new Error(`--last attend un entier positif, reçu « ${v} »`);
+        opts.last = n;
+      }
+    }
+  }
+  return opts;
+}
+
+/**
+ * Heure locale `HH:MM:SS.mmm` d'un horodatage — la forme du journal texte, pour
+ * qu'un même événement lu dans ses deux formes se reconnaisse.
+ *
+ * @param ms - horodatage en millisecondes.
+ * @returns l'heure formatée.
+ */
+function timeOfDay(ms) {
+  const d = new Date(ms);
+  const p = (n, w = 2) => String(n).padStart(w, "0");
+  return `${p(d.getHours())}:${p(d.getMinutes())}:${p(d.getSeconds())}.${p(d.getMilliseconds(), 3)}`;
+}
+
+/**
+ * Découpe un journal en événements, quelle que soit sa forme (texte ou JSON par ligne).
+ *
+ * Les lignes d'une même erreur — même heure, même émetteur, même sévérité, ou
+ * pile d'appels qui suit — forment UN événement : une pile de sept lignes est
+ * une erreur, pas sept.
+ *
+ * @param text - le contenu du journal.
+ * @param source - le nom du fichier, rendu avec chaque événement.
+ * @returns les événements, dans l'ordre du journal.
+ */
+export function extractEvents(text, source) {
+  const events = [];
+  let last = null;
+  for (const rawLine of text.split(/\r?\n/u)) {
+    const line = rawLine.replace(ANSI, "");
+    if (line.trim() === "") continue;
+    let entry = null;
+    if (line.startsWith("{")) {
+      try {
+        const o = JSON.parse(line);
+        if (typeof o.severityName === "string" && o.severityName in SEVERITY) {
+          entry = {
+            time:
+              typeof o.timeStamp === "number" ? timeOfDay(o.timeStamp) : null,
+            severity: o.severityName,
+            msgid: String(o.msgid ?? ""),
+            message:
+              typeof o.payload === "string"
+                ? o.payload
+                : JSON.stringify(o.payload),
+          };
+        }
+      } catch {
+        // Une ligne JSON tronquée (écriture en cours) n'est pas une erreur du journal.
+      }
+    } else {
+      const m = PDU_LINE.exec(line);
+      if (m)
+        entry = {
+          time: m[1],
+          severity: m[2],
+          msgid: m[3].trim(),
+          message: m[4],
+        };
+      else {
+        const r = RAW_ERROR.exec(line.trim());
+        if (r)
+          entry = {
+            time: null,
+            severity: "ERROR",
+            msgid: "node",
+            message: line.trim(),
+          };
+        else if (last && STACK_LINE.test(line)) {
+          last.detail.push(line.trim());
+          continue;
+        }
+      }
+    }
+    if (entry === null) {
+      last = null;
+      continue;
+    }
+    const sameError =
+      last !== null &&
+      entry.time !== null &&
+      last.time === entry.time &&
+      last.msgid === entry.msgid &&
+      last.severity === entry.severity;
+    if (sameError) {
+      last.detail.push(entry.message);
+      continue;
+    }
+    last = { ...entry, source, detail: [] };
+    events.push(last);
+  }
+  return events;
+}
+
+/**
+ * Garde ce qui compte et fusionne les répétitions.
+ *
+ * Deux événements identiques (même sévérité, émetteur et message) n'en font
+ * qu'un, compté — qu'ils viennent d'un même fichier ou des deux formes du même
+ * journal. L'ordre rendu est chronologique, par dernière occurrence.
+ *
+ * @param events - les événements extraits.
+ * @param options - `warnings` garde aussi les avertissements.
+ * @returns les erreurs distinctes, chacune avec son nombre, sa première et sa dernière heure, et sa piste.
+ */
+export function summarize(events, { warnings = false } = {}) {
+  const ceiling = warnings ? SEVERITY.WARNING : SEVERITY.ERROR;
+  const byKey = new Map();
+  const seen = new Set();
+  for (const e of events) {
+    if (SEVERITY[e.severity] > ceiling) continue;
+    // Le même événement lu dans ses deux formes (texte ET JSON) ne compte qu'une fois.
+    const occurrence = `${e.time}|${e.severity}|${e.msgid}|${e.message}`;
+    if (e.time !== null && seen.has(occurrence)) continue;
+    seen.add(occurrence);
+    const key = `${e.severity}|${e.msgid}|${e.message}`;
+    const known = byKey.get(key);
+    if (known) {
+      known.count++;
+      known.lastTime = e.time ?? known.lastTime;
+      byKey.delete(key);
+      byKey.set(key, known);
+      continue;
+    }
+    const text = [e.message, ...e.detail].join("\n");
+    byKey.set(key, {
+      severity: e.severity,
+      msgid: e.msgid,
+      message: e.message,
+      detail: e.detail,
+      source: e.source,
+      count: 1,
+      firstTime: e.time,
+      lastTime: e.time,
+      hint: HINTS.find((h) => h.when.test(text))?.hint ?? null,
+    });
+  }
+  return [...byKey.values()];
+}
+
+/**
+ * Lit la fin d'un fichier — tout, s'il est sous le plafond.
+ *
+ * @param file - chemin du fichier.
+ * @returns le texte relu.
+ */
+function readTail(file) {
+  // Une seule ouverture : taille et lecture sur le MÊME descripteur — le chemin
+  // peut changer entre un `stat` et un `read` (js/file-system-race).
+  const fd = openSync(file, "r");
+  try {
+    const size = fstatSync(fd).size;
+    if (size <= MAX_SCAN_BYTES) return readFileSync(fd, "utf8");
+    const buf = Buffer.alloc(MAX_SCAN_BYTES);
+    readSync(fd, buf, 0, MAX_SCAN_BYTES, size - MAX_SCAN_BYTES);
+    // La première ligne est coupée en plein milieu : on la jette.
+    return buf.toString("utf8").replace(/^[^\n]*\n/u, "");
+  } finally {
+    closeSync(fd);
+  }
+}
+
+/**
+ * Les journaux à lire : ceux donnés, sinon ceux du dossier `logs/` du projet.
+ *
+ * @param opts - les options lues.
+ * @returns les fichiers lisibles, du plus ancien au plus récent.
+ */
+export function journalFiles(opts) {
+  if (opts.files.length > 0)
+    return opts.files.map((f) => path.resolve(opts.root, f));
+  const dir = path.join(opts.root, "logs");
+  let names;
+  try {
+    names = readdirSync(dir);
+  } catch {
+    return [];
+  }
+  return names
+    .filter((n) => n.endsWith(".log") || n.endsWith(".jsonl"))
+    .map((n) => path.join(dir, n))
+    .sort((a, b) => statSync(a).mtimeMs - statSync(b).mtimeMs);
+}
+
+/** Âge lisible d'un fichier : un journal d'hier ne parle pas de la panne d'aujourd'hui. */
+function age(ms) {
+  const min = Math.round((Date.now() - ms) / 60_000);
+  if (min < 1) return "moins d'une minute";
+  if (min < 120) return `${min} min`;
+  return `${Math.round(min / 60)} h`;
+}
+
+const USAGE = `Usage : node log-errors.mjs [journal…] [--warnings] [--last N] [--json] [--root DIR]
+
+Sans fichier : lit logs/*.log et logs/*.jsonl du projet.
+Sorties : 0 aucune erreur · 1 au moins une erreur · 64 usage · 66 aucun journal lisible.`;
+
+/**
+ * Point d'entrée.
+ *
+ * @returns le code de sortie.
+ */
+export function main(argv = process.argv.slice(2)) {
+  let opts;
+  try {
+    opts = parseArgs(argv);
+  } catch (e) {
+    process.stderr.write(`${e.message}\n\n${USAGE}\n`);
+    return 64;
+  }
+  if (opts.help) {
+    process.stdout.write(`${USAGE}\n`);
+    return 0;
+  }
+  const files = journalFiles(opts);
+  const read = [];
+  const events = [];
+  for (const file of files) {
+    let text;
+    try {
+      text = readTail(file);
+    } catch (e) {
+      process.stderr.write(`illisible : ${file} — ${e.message}\n`);
+      continue;
+    }
+    const rel = path.relative(opts.root, file) || file;
+    read.push({ file: rel, age: age(statSync(file).mtimeMs) });
+    events.push(...extractEvents(text, rel));
+  }
+  if (read.length === 0) {
+    process.stderr.write(
+      "Aucun journal lisible.\n" +
+        "En développement, le journal part sur la SORTIE du terminal qui a lancé le serveur, pas dans un fichier.\n" +
+        "Pour l'avoir ici : `npx nodefony development --detach` (journal dans logs/nodefony-detached.log),\n" +
+        "ou redirige la sortie dans un fichier, puis passe-le en argument.\n",
+    );
+    return 66;
+  }
+  const all = summarize(events, opts);
+  const shown = all.slice(-opts.last);
+  if (opts.json) {
+    process.stdout.write(
+      `${JSON.stringify({ read, total: all.length, errors: shown }, null, 2)}\n`,
+    );
+    return all.length > 0 ? 1 : 0;
+  }
+  process.stdout.write(
+    `Journaux lus : ${read.map((r) => `${r.file} (écrit il y a ${r.age})`).join(", ")}\n\n`,
+  );
+  if (all.length === 0) {
+    process.stdout.write(
+      `Aucune erreur${opts.warnings ? " ni avertissement" : ""}.\n`,
+    );
+    return 0;
+  }
+  process.stdout.write(
+    `${all.length} erreur${all.length > 1 ? "s" : ""} distincte${all.length > 1 ? "s" : ""}` +
+      `${all.length > shown.length ? ` — les ${shown.length} plus récentes` : ""}\n\n`,
+  );
+  for (const e of shown) {
+    const when =
+      e.count > 1
+        ? `${e.firstTime ?? "?"} → ${e.lastTime ?? "?"}, ×${e.count}`
+        : (e.firstTime ?? "heure inconnue");
+    process.stdout.write(
+      `${e.severity} ${e.msgid} [${e.source}, ${when}]\n  ${e.message}\n`,
+    );
+    for (const d of e.detail.slice(0, 4)) process.stdout.write(`    ${d}\n`);
+    if (e.detail.length > 4)
+      process.stdout.write(`    … ${e.detail.length - 4} ligne(s) de plus\n`);
+    if (e.hint) process.stdout.write(`  ➜ ${e.hint}\n`);
+    process.stdout.write("\n");
+  }
+  return 1;
+}
+
+// Exécuté directement (et non importé par son test) : rendre le code.
+// La comparaison passe par une URL, jamais par un chemin : sous Windows, `D:\…`
+// verrait son `d:` lu comme un protocole.
+if (
+  process.argv[1] !== undefined &&
+  // Chemins RÉELS des deux côtés : Node résout `import.meta.url` en suivant
+  // les liens, pas `argv[1]` — lancé par `/var/…` (macOS) ou un dossier lié,
+  // la comparaison brute échouait et le script ne faisait RIEN.
+  realpathSync(process.argv[1]) === fileURLToPath(import.meta.url)
+) {
+  process.exitCode = main();
+}

package/skills/nodefony-upgrade/SKILL.md

@@ -0,0 +1,130 @@
+---
+name: nodefony-upgrade
+description: >
+  Monte une application Nodefony vers une nouvelle version du framework sans rien laisser derrière :
+  tous les paquets ensemble et sous le bon canal, puis `nodefony upgrade` pour la documentation des
+  agents, les skills et les fichiers livrés qu'un `npm install` ne refait pas, puis les ruptures
+  annoncées corrigées dans le code, le schéma migré et la preuve que tout tient. À charger AVANT de
+  lancer la montée de version, pas après un premier rouge. Une panne sans rapport avec une montée →
+  `nodefony-troubleshoot`.
+  Déclencheurs : "monter nodefony de version", "mettre à jour nodefony", "passer à la nouvelle
+  beta", "upgrade nodefony", "npm update nodefony", "une nouvelle version est sortie", "mes paquets
+  nodefony sont en retard", "après la mise à jour plus rien ne compile", "AGENTS.md est périmé".
+metadata:
+  version: 1.0.0
+---
+
+# nodefony-upgrade — les paquets, puis l'application, puis la preuve
+
+> **Maintenance** : vérité courante, jamais un journal. Éditer en place ; l'historique vit dans
+> `git log`. Pas de `references/` : ce qui doit atteindre un agent s'exécute ou vit dans ce corps.
+
+## Passer la main
+
+| Ce que tu fais en réalité                                        | Le skill                  |
+| ---------------------------------------------------------------- | ------------------------- |
+| Rien n'a été mis à jour, et quelque chose a cessé de marcher     | `nodefony-troubleshoot`   |
+| Une rupture touche une table ou une colonne : migration à écrire | `nodefony-migrate-schema` |
+| Une rupture touche la connexion, `/me`, l'identité de la requête | `nodefony-authentication` |
+| Monter l'image et la déployer une fois l'application au niveau   | `nodefony-devops`         |
+| Coder autre chose dans la foulée                                 | `nodefony-dev`            |
+
+## 1. La règle — trois couches, trois gestes
+
+Une montée de version touche trois couches, et `npm install` n'en fait qu'une :
+
+1. **Les paquets** (`node_modules`) — `npm install`.
+2. **Ce que les paquets ont déposé dans l'application** à sa création : le bloc framework
+   d'`AGENTS.md`, les pointeurs de `.agents/skills/`, les copies livrées (décor Keycloak…). Ils
+   restent sur l'ancienne version sans que rien ne casse — `nodefony upgrade`.
+3. **Ton code**, quand la version annonce une rupture — toi, guidé par le changelog et le
+   compilateur.
+
+Sauter la couche 2 ne fait échouer aucun test : un agent lit simplement une porte qui décrit
+l'ancienne version. Sauter la couche 3 se voit au premier `typecheck`.
+
+## 2. La procédure
+
+**Avant** : arbre propre, tests verts. Une montée sur un arbre déjà rouge mélange deux pannes.
+
+```bash
+git status
+npm test
+npx nodefony outdated
+```
+
+`outdated` liste les paquets en retard, regroupés. Note la version cible.
+
+**Monter TOUS les paquets Nodefony, ensemble, sous le bon canal.** Ils sortent verrouillés : même
+version pour `nodefony` et chaque `@nodefony/*`, devDependencies comprises (`@nodefony/devkit`
+porte les skills). Nomme chacun de ceux que ton `package.json` déclare :
+
+```bash
+npm install nodefony@beta @nodefony/http@beta @nodefony/framework@beta @nodefony/security@beta
+npm install -D @nodefony/devkit@beta
+```
+
+⚠️ Pendant la série 10, **`beta` est le canal de la préversion** ; `latest` sert encore l'ancienne
+lignée 7 en JavaScript. Un `npm install nodefony` sans canal fait REDESCENDRE l'application.
+
+**Remettre l'application au niveau des paquets** :
+
+```bash
+npx nodefony upgrade
+```
+
+Elle réécrit le bloc framework d'`AGENTS.md` (le texte hors des marqueurs `<!-- nodefony:start -->`
+/ `<!-- nodefony:end -->` ne bouge pas), pose les pointeurs des skills apparus, rafraîchit les
+copies livrées restées intactes. Ce qu'elle ne tranche pas est listé sous « À trancher à la main » :
+une copie que l'application a retouchée, un `SKILL.md` écrit à la main, un skill que plus aucun
+paquet ne livre. **Lis cette liste** : chaque ligne est une décision qui t'appartient.
+
+**Lire les ruptures annoncées.** Le changelog est livré dans le paquet `nodefony` :
+`node_modules/nodefony/CHANGELOG.md`, celui de la version INSTALLÉE — lu après la montée, il
+couvre donc toutes les versions franchies, sans réseau. Absent (une version qui ne le livrait pas
+encore) : `https://github.com/nodefony/nodefony-core/blob/main/CHANGELOG.md`. Dans la
+section de chaque version franchie, les entrées marquées **`(breaking)`** sont celles qui
+demandent une retouche de ton code — un nom renvoyé qui change, une option retirée, un défaut
+inversé. Une rupture de comportement ne se voit pas au compilateur : seul le changelog la dit.
+
+**Reconstruire, puis laisser le compilateur et les tests désigner le reste** :
+
+```bash
+npm run build
+npm run typecheck
+npm test
+npx nodefony doctor
+```
+
+Un symbole renommé ou retiré sort au `typecheck` avec son fichier et sa ligne. Un symbole
+**déprécié** apparaît barré dans l'éditeur : il marche encore toute la série, son TSDoc nomme le
+remplaçant. `doctor` signale ce qui reste en retard, chaque constat avec son geste.
+
+**Si une rupture touche le schéma**, ou si le changelog l'annonce : `npx nodefony orm:migrate:status`,
+puis la procédure de `nodefony-migrate-schema`.
+
+## 3. Pièges
+
+- **Monter un paquet seul n'est pas monter Nodefony.** Deux versions différentes de `nodefony`
+  dans `node_modules` se voient comme deux copies du cœur : l'application démarre amputée, ou pas
+  du tout. `npm ls nodefony` doit rendre une seule version.
+- **Le canal par défaut ment pendant la série 10** : sans `@beta`, npm installe la 7.
+- **Un vert ne prouve pas que la documentation des agents a suivi.** Seuls `doctor` ou
+  `npx nodefony upgrade --check` le voient.
+- **`upgrade` ne recrée pas un `AGENTS.md` supprimé** : l'absence peut être un choix. Elle le dit.
+- **Ne corrige pas une copie livrée « en retard » à la main** : si elle est intacte, `upgrade` la
+  remplace ; si tu l'as retouchée, reporte tes retouches sur la nouvelle version du paquet, à la
+  main et en connaissance de cause.
+
+## 4. Gate — la montée est faite quand
+
+```bash
+npx nodefony upgrade --check
+npm run typecheck
+npm test
+npx nodefony doctor
+```
+
+`upgrade --check` sort en 0 (sinon il dit ce qui reste en retard), le typecheck et les tests sont
+verts, `doctor` ne signale rien de neuf. En intégration continue, `upgrade --check` refuse une
+branche qui a monté ses paquets sans remettre l'application au niveau.

package/dist/_virtual/_@oxc-project_runtime@0.152.0/helpers/esm/decorateMetadata.js

@@ -1,6 +0,0 @@
-//#region \0@oxc-project+runtime@0.152.0/helpers/esm/decorateMetadata.js
-function __decorateMetadata(k, v) {
-	if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
-}
-//#endregion
-export { __decorateMetadata as default };