@nodefony/devkit 10.0.0-beta.1 → 10.0.0-beta.3

package/skills/nodefony-troubleshoot/SKILL.md

@@ -0,0 +1,151 @@
+---
+name: nodefony-troubleshoot
+description: >
+  Dépanne une application Nodefony en partant du SYMPTÔME constaté — démarrage qui échoue,
+  route en 404, refus 401 ou 403 inattendu, erreur au journal, colonne absente, tests rouges
+  d'un coup — et donne pour chacun le premier geste, la commande qui le constate et le skill
+  qui porte le détail. Extrait les erreurs du journal par un script (regroupées, datées, avec
+  leur piste) au lieu de le lire en entier. À charger DÈS qu'une chose qui marchait ne marche
+  plus, AVANT de lire les sources ou de contourner la panne. Coder une fonctionnalité →
+  `nodefony-dev`.
+  Déclencheurs : "l'application ne démarre plus", "le serveur plante au démarrage", "ma route
+  répond 404", "ça marchait hier", "j'ai une erreur dans le journal", "erreur dans les logs",
+  "plus rien ne répond", "tous mes tests sont rouges", "pourquoi ça plante", "dépanner",
+  "diagnostiquer une panne", "stack trace", "EADDRINUSE", "ECONNREFUSED".
+metadata:
+  version: 1.0.0
+---
+
+# nodefony-troubleshoot — du symptôme au geste, sans contourner
+
+> **Maintenance** : vérité courante, jamais un journal. Éditer en place ; l'historique vit dans
+> `git log`. Pas de `references/`, comme `nodefony-dev` et pour la même raison mesurée : une page
+> de `references/` n'est presque jamais ouverte par un agent, un script cité comme commande l'est.
+> 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                  |
+| -------------------------------------------------------------------- | ------------------------- |
+| Tu codes une fonctionnalité, rien n'est cassé                        | `nodefony-dev`            |
+| Le refus 401/403 vient d'une route que tu protèges ou ouvres         | `nodefony-protect-route`  |
+| La connexion elle-même échoue : mot de passe, second facteur, retour | `nodefony-authentication` |
+| La base n'a pas la colonne ou la table que l'entité déclare          | `nodefony-migrate-schema` |
+| Le symptôme est À L'ÉCRAN : rien ne s'affiche, erreur de console     | `nodefony-browser`        |
+| La panne n'apparaît qu'en conteneur, en production, au déploiement   | `nodefony-devops`         |
+
+## 1. La règle — constater, puis corriger la cause
+
+**Une panne se CONSTATE avant de se corriger.** L'application sait dire ce qui ne va pas : son
+diagnostic, ses routes montées, son journal. Lire les sources pour deviner, c'est reconstruire à la
+main ce qu'une commande rend en une seconde — et se tromper sur ce qui est réellement chargé.
+
+**Ne contourne jamais une panne.** Élargir une zone pour faire taire un 401, retirer une garde,
+sérialiser une suite pour faire passer un rouge, relâcher une assertion, effacer la base : chacun
+fait disparaître le symptôme et garde la cause, qui revient ailleurs — souvent en production. Si la
+cause t'échappe, dis-le, avec ce que tu as constaté.
+
+## 2. Le symptôme → le premier geste
+
+| Symptôme                                                              | Premier geste                                                          | Puis                                                                                                      |
+| --------------------------------------------------------------------- | ---------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
+| L'application ne démarre pas, ou démarre puis s'arrête                | `npx nodefony doctor`                                                  | le journal (§3) ; sortie `78` = clé de configuration refusée, elle est NOMMÉE                             |
+| Elle démarre, mais quelque chose manque (module, base, fournisseur)   | `npx nodefony doctor --live`                                           | `var/last-boot.json` : le bilan du dernier démarrage, daté                                                |
+| Le superviseur avale le message de plantage                           | lance l'enfant seul : `NF_DEV_CHILD=1` puis `npx nodefony development` | le plantage brut s'affiche                                                                                |
+| Une route répond `404`                                                | `npx nodefony inspect routes --json`                                   | absente → `npm run build` ; présente → le chemin MONTÉ diffère (§4)                                       |
+| TOUT répond `404`, même les routes du gabarit                         | `npx nodefony status`                                                  | un autre serveur tient les ports, ou le tien a glissé (§4)                                                |
+| Refus `401` ou `403` inattendu                                        | lire le corps et l'en-tête `WWW-Authenticate` de la réponse            | `nodefony-protect-route` (zone, rôle, jeton anti-falsification)                                           |
+| `401` avec `error="insufficient_user_authentication"`                 | la route exige une connexion récente ou un second facteur              | `nodefony-authentication`                                                                                 |
+| `403` « Credentials must be sent over HTTPS »                         | un mot de passe envoyé en HTTP clair, refusé en production             | servir en HTTPS, ou déclarer le proxy TLS (`trustProxy`)                                                  |
+| Une erreur dans le journal                                            | le script du §3                                                        | la piste qu'il donne, sinon le message lui-même                                                           |
+| « colonne inexistante », « no such table », migrations à appliquer    | `npx nodefony doctor --live`                                           | `nodefony-migrate-schema`                                                                                 |
+| Des dizaines de tests d'intégration rouges d'un coup (`ECONNREFUSED`) | `npx nodefony status`                                                  | ils FRAPPENT un serveur, ils ne le lancent pas : il est éteint. En e2e, laisse la commande gérer le cycle |
+| `nodefony <commande>` échoue là où `npm run dev` réussit              | `npm ls nodefony`                                                      | deux copies du framework dans le processus (§4)                                                           |
+
+**Lis toute la réponse d'une commande de diagnostic.** Ne la tronque jamais (`| head`, une
+recherche dans sa sortie) : la ligne qui nomme la cause est presque toujours dans la partie coupée.
+
+## 3. Le journal — extraire, pas lire
+
+Un journal de développement fait des milliers de lignes, presque toutes saines. Le script lit tout,
+garde les erreurs, recolle chaque pile d'appels à la ligne qui l'a levée, fusionne les répétitions,
+date ce qu'il a lu, et nomme le premier geste quand la cause est établie :
+
+```bash
+node node_modules/@nodefony/devkit/skills/nodefony-troubleshoot/scripts/log-errors.mjs
+node node_modules/@nodefony/devkit/skills/nodefony-troubleshoot/scripts/log-errors.mjs logs/dev.log
+node node_modules/@nodefony/devkit/skills/nodefony-troubleshoot/scripts/log-errors.mjs --warnings --last 40
+node node_modules/@nodefony/devkit/skills/nodefony-troubleshoot/scripts/log-errors.mjs --json
+```
+
+Sans argument, il lit `logs/*.log` et `logs/*.jsonl`. Sorties : `0` aucune erreur · `1` au moins
+une · `64` usage · `66` aucun journal lisible.
+
+⚠️ **En développement, le journal part sur la sortie du TERMINAL, pas dans un fichier.** Le script
+répond alors `66` et dit comment l'obtenir : lancer le serveur avec `npx nodefony development
+--detach` (journal dans `logs/nodefony-detached.log`), ou rediriger la sortie dans un fichier qu'on
+lui passe. **Lis l'âge** qu'il affiche pour chaque fichier : un journal d'hier ne parle pas de la
+panne d'aujourd'hui.
+
+⚠️ **Une erreur du journal n'est pas toujours une panne.** Un port pris par l'outil du front se
+rattrape seul sur le suivant (la ligne « retrying » qui suit le dit) ; un `CRITIC SIGTERM` est un
+arrêt demandé. Le script le signale quand il le reconnaît — sinon, relie l'erreur au symptôme avant
+de la corriger.
+
+## 4. Les pannes qui trompent
+
+Chacune a déjà coûté au moins une heure à quelqu'un.
+
+- **Ta route répond `404` alors qu'elle existe dans les sources.** Le runtime charge `dist/`, pas
+  le source : `npm run build`. C'est la cause n°1.
+- **Une classe que rien ne déclare compile, passe ses tests, et casse au démarrage suivant** —
+  entité hors `@entities([…])`, controller hors `@controllers([…])`. Table jamais créée, route en
+  `404`. C'est le mode d'échec de la COPIE : on recopie le voisin au lieu d'appeler le générateur,
+  qui, lui, déclare. `npx nodefony doctor` la NOMME.
+- **Ta route NEUVE répond `404` et le `dist/` est à jour** : elle n'est pas montée où tu crois. Le
+  chemin réel est le PRÉFIXE de son controller suivi du `path` de la route — une action
+  `path: "/widget"` dans un controller `@controller("/api")` répond sur `/api/widget`.
+  `npx nodefony inspect routes --json` donne le chemin MONTÉ.
+- **TOUT répond `404`** : un AUTRE serveur tient les ports — ou LE TIEN a glissé, le port voulu
+  étant pris. `npx nodefony status` montre les ports RÉELS, pas ceux que tu as configurés, et
+  NOMME le projet voisin.
+- **Une clé de configuration mal orthographiée ARRÊTE le démarrage** (sortie `78`), en la nommant.
+  Une clé retirée par une version du framework produit le même arrêt après un `npm update` : lis
+  le message, il nomme la clé.
+- 🔴 **`nodefony <commande>` échoue là où `npm run dev` réussit, sur la MÊME application** : DEUX
+  paquets `nodefony` tournent dans le processus — un binaire lié ailleurs (installation globale,
+  `npm link`) exécute un noyau pendant que l'application importe le sien. Chaque copie a ses
+  propres classes, son contexte de requête et ses registres d'injection : un module construit à la
+  frontière perd son container SANS la moindre erreur — il figure dans la liste des modules et ne
+  fait rien. ⚠️ Les deux copies peuvent être la MÊME version ; deux fichiers distincts suffisent,
+  il n'y a aucune incohérence à repérer. `npm ls nodefony` liste les copies (« deduped » partout = une seule) ;
+  `NF_CLI_DEBUG=1 nodefony --version` dit quel CLI s'exécute.
+- **`localhost` et `127.0.0.1` te jouent des tours** : ce sont deux ORIGINES distinctes — cookies,
+  cache et passkeys ne les partagent pas. Une session ouverte sur l'une n'existe pas sur l'autre :
+  `401` assuré. Une seule origine en développement, partout, URL ouverte comme callbacks.
+- **Ton application a démarré AMPUTÉE et tout a l'air sain** — base injoignable, module écarté par
+  sa politique. Seul `npx nodefony doctor` le dit, en relisant `var/last-boot.json`. ⚠️ Ce bilan
+  a un ÂGE : il décrit le **dernier démarrage**, et une commande console ne l'écrase pas — lis la
+  date avant d'en conclure.
+- **Une suite lancée contre un serveur en `production` reçoit `404` partout** : les modules
+  `policy:"dev"` n'y sont pas. `NF_WITH_DEV_MODULES=1` déroge pour 30 minutes
+  (`NF_WITH_DEV_MODULES_TTL_MIN`, 4 h au plus), et le `CRITIC « arrêt automatique … dérogation »`
+  du journal est cette garde qui se referme — pas une panne.
+- **Un test vert seul et rouge en suite accuse une RESSOURCE PARTAGÉE**, pas ton code : base ou
+  index réutilisé, port, store jamais purgé, assertion `count === N` qui suppose une table vierge.
+  Lance deux fichiers ENSEMBLE pour isoler la paire, puis cloisonne. **Ne sérialise jamais la
+  suite** pour faire passer le rouge : tu masques la cause et tu paies la lenteur à chaque
+  exécution.
+- **Les routes authentifiées plafonnent quand le reste tient la charge** : le stockage de session
+  par défaut est SYNCHRONE — chaque reprise bloque la boucle d'événements. Compare une route
+  anonyme et une route authentifiée AVANT d'accuser TLS ou le pare-feu ; passe le stockage sur
+  redis pour la charge.
+
+## 5. Avant de dire « réparé »
+
+1. **Rejoue le symptôme d'origine** — la même requête, la même commande — et constate qu'il a
+   disparu. Un correctif qu'on n'a pas vu agir sur le symptôme est une hypothèse.
+2. **`npx nodefony doctor`** ne signale plus rien de neuf.
+3. **`npm run verify`** : le correctif n'a rien cassé ailleurs.
+4. **Dis la cause**, pas seulement le geste : « le `dist/` était en retard » apprend quelque chose
+   au suivant ; « j'ai relancé le build » ne lui apprend rien.

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();
+}