nodefony 7.0.2 → 10.0.0-alpha.2

package/templates/app/base/oxlintrc.json.tpl

@@ -0,0 +1,127 @@
+{
+  "$schema": "./node_modules/oxlint/configuration_schema.json",
+  "plugins": ["typescript", "unicorn", "oxc", "promise", "import"],
+  "categories": {
+    "correctness": "error",
+    "suspicious": "warn",
+    "perf": "warn"
+  },
+  "env": { "node": true, "es2024": true },
+  "ignorePatterns": ["node_modules/**", "dist/**", "var/**", "*.log"],
+  "rules": {
+    "no-unused-vars": [
+      "error",
+      {
+        "argsIgnorePattern": "^_",
+        "varsIgnorePattern": "^_",
+        "caughtErrors": "none"
+      }
+    ],
+    "no-restricted-imports": [
+      "error",
+      {
+        "paths": [
+          {
+            "name": "assert",
+            "message": "Préfixe Node obligatoire : importe \"node:assert\"."
+          },
+          {
+            "name": "buffer",
+            "message": "Préfixe Node obligatoire : importe \"node:buffer\"."
+          },
+          {
+            "name": "child_process",
+            "message": "Préfixe Node obligatoire : importe \"node:child_process\"."
+          },
+          {
+            "name": "crypto",
+            "message": "Préfixe Node obligatoire : importe \"node:crypto\"."
+          },
+          {
+            "name": "events",
+            "message": "Préfixe Node obligatoire : importe \"node:events\"."
+          },
+          {
+            "name": "fs",
+            "message": "Préfixe Node obligatoire : importe \"node:fs\"."
+          },
+          {
+            "name": "fs/promises",
+            "message": "Préfixe Node obligatoire : importe \"node:fs/promises\"."
+          },
+          {
+            "name": "http",
+            "message": "Préfixe Node obligatoire : importe \"node:http\"."
+          },
+          {
+            "name": "http2",
+            "message": "Préfixe Node obligatoire : importe \"node:http2\"."
+          },
+          {
+            "name": "https",
+            "message": "Préfixe Node obligatoire : importe \"node:https\"."
+          },
+          {
+            "name": "net",
+            "message": "Préfixe Node obligatoire : importe \"node:net\"."
+          },
+          {
+            "name": "os",
+            "message": "Préfixe Node obligatoire : importe \"node:os\"."
+          },
+          {
+            "name": "path",
+            "message": "Préfixe Node obligatoire : importe \"node:path\"."
+          },
+          {
+            "name": "process",
+            "message": "Préfixe Node obligatoire : importe \"node:process\"."
+          },
+          {
+            "name": "stream",
+            "message": "Préfixe Node obligatoire : importe \"node:stream\"."
+          },
+          {
+            "name": "timers",
+            "message": "Préfixe Node obligatoire : importe \"node:timers\"."
+          },
+          {
+            "name": "url",
+            "message": "Préfixe Node obligatoire : importe \"node:url\"."
+          },
+          {
+            "name": "util",
+            "message": "Préfixe Node obligatoire : importe \"node:util\"."
+          },
+          {
+            "name": "worker_threads",
+            "message": "Préfixe Node obligatoire : importe \"node:worker_threads\"."
+          }
+        ]
+      }
+    ],
+    "typescript/no-explicit-any": "warn",
+    "typescript/ban-ts-comment": "warn",
+    // ESM strict : une application Nodefony n'écrit jamais `require`.
+    "typescript/no-require-imports": "warn",
+    "no-eval": "error",
+    "no-new-func": "error",
+    "no-await-in-loop": "off",
+    "no-console": "off",
+    "unicorn/no-array-reverse": "off",
+    "unicorn/consistent-function-scoping": "off",
+    "typescript/no-extraneous-class": "off"
+  },
+  "overrides": [
+    {
+      "files": ["**/*.test.ts", "**/*.spec.ts", "tests/**/*.ts"],
+      "rules": {
+        "typescript/no-explicit-any": "off",
+        "no-unused-vars": "off",
+        "no-unused-expressions": "off",
+        "no-restricted-imports": "off",
+        "promise/no-callback-in-promise": "off"
+      }
+    }
+  ]
+}

package/templates/app/base/package.json.tpl

@@ -0,0 +1,75 @@
+{
+  "name": "<%= it.appName %>",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "description": "Application Nodefony — générée par `nodefony create app`",
+  "main": "dist/index.js",
+  "engines": {
+    "node": ">=24.0.0"
+  },
+<% if (it.complete && it.dialect === "sqlite") { %>  "allowScripts": {
+    "better-sqlite3": false
+  },
+<% } %>  "scripts": {
+    "prepare": "node --eval \"const f=require('node:fs');if(f.existsSync('.githooks'))try{require('node:child_process').execSync('git config core.hooksPath .githooks',{stdio:'ignore'})}catch{}\"",
+    "dev": "nodefony development",
+    "build": "rolldown -c rolldown.config.ts<% if (it.front) { %> && nodefony frontend:build<% } %>",
+    "start": "nodefony production",
+    "stop": "nodefony stop",
+    "status": "nodefony status",
+    "test": "vitest run",
+    "coverage:setup": "npm i -D @vitest/coverage-v8",
+    "coverage": "vitest run --coverage",
+    "test:e2e": "npm run build && vitest run -c vitest.e2e.config.ts",
+    "typecheck": "tsgo --noEmit",
+    "verify": "npm run typecheck && npm run lint && npm run format:check && npm test && npm run doctor",
+    "doctor": "nodefony doctor",
+    "inspect": "nodefony inspect",
+    "ai:sync": "nodefony ai:sync",
+    "see:setup": "npm i -D playwright axe-core",
+    "see": "node node_modules/@nodefony/devkit/skills/nodefony-browser/scripts/inspect.mjs",
+    "watch:screen": "node node_modules/@nodefony/devkit/skills/nodefony-browser/scripts/watch.mjs",
+    "audit:setup": "npm i -D playwright lighthouse",
+    "audit:web": "node node_modules/@nodefony/devkit/skills/nodefony-browser/scripts/audit.mjs",
+    "clean": "node --eval \"require('node:fs').rmSync('dist',{recursive:true,force:true})\"",
+    "lint": "oxlint --deny-warnings",
+    "format": "prettier --write .",
+    "format:check": "prettier --check ."<% if (it.complete) { %>,
+    "infra:up": "docker compose up -d",
+    "infra:down": "docker compose down"<% } %>
+  },
+  "dependencies": {
+    "nodefony": "^<%= it.nodefonyVersion %>",
+    "@nodefony/http": "^<%= it.nodefonyVersion %>",
+    "@nodefony/framework": "^<%= it.nodefonyVersion %>",
+<% if (it.complete) { %>    "@nodefony/orm-core": "^<%= it.nodefonyVersion %>",
+    "@nodefony/drizzle": "^<%= it.nodefonyVersion %>",
+    "drizzle-orm": "<%= it.pkg["drizzle-orm"] %>",
+<% if (it.dialect === "postgres") { %>    "pg": "<%= it.pkg["pg"] %>",
+<% } else if (it.dialect === "mysql") { %>    "mysql2": "<%= it.pkg["mysql2"] %>",
+<% } else { %>    "better-sqlite3": "<%= it.pkg["better-sqlite3"] %>",
+<% } %>    "@nodefony/user": "^<%= it.nodefonyVersion %>",
+    "@node-rs/argon2": "<%= it.pkg["@node-rs/argon2"] %>",
+    "@nodefony/realtime": "^<%= it.nodefonyVersion %>",
+    "@nodefony/security": "^<%= it.nodefonyVersion %>",
+    "@nodefony/frontend": "^<%= it.nodefonyVersion %>",
+    "@nodefony/studio": "^<%= it.nodefonyVersion %>",
+    "@nodefony/redis": "^<%= it.nodefonyVersion %>",
+<% } else if (it.front) { %>    "@nodefony/frontend": "^<%= it.nodefonyVersion %>",
+<% } %><% if (it.front) { for (const [n, v] of Object.entries(it.front.deps)) { %>    "<%= n %>": "<%= v %>",
+<% } } %>    "zod": "<%= it.pkg["zod"] %>"
+  },
+  "devDependencies": {
+    "@nodefony/devkit": "^<%= it.nodefonyVersion %>",
+    "@types/node": "<%= it.pkg["@types/node"] %>",
+    "drizzle-kit": "<%= it.pkg["drizzle-kit"] %>",
+    "@typescript/native-preview": "<%= it.pkg["@typescript/native-preview"] %>",
+    "oxlint": "<%= it.pkg["oxlint"] %>",
+    "prettier": "<%= it.pkg["prettier"] %>",
+    "rolldown": "<%= it.pkg["rolldown"] %>",
+<% if (it.front) { for (const [n, v] of Object.entries(it.front.devDeps)) { %>    "<%= n %>": "<%= v %>",
+<% } } %>    "typescript": "<%= it.pkg["typescript"] %>",
+    "vitest": "<%= it.pkg["vitest"] %>"
+  }
+}

package/templates/app/base/prettierignore.tpl

@@ -0,0 +1,24 @@
+# Ce que le formateur ne doit PAS toucher.
+#
+# `npm run format` lance `prettier --write .` sur tout le projet. Prettier
+# écarte `node_modules` de lui-même — mais PAS `dist/`, ni `var/`, ni les
+# artefacts du build front. Sans ce fichier, un seul `npm run format` reformate
+# le BUILD : des milliers de lignes modifiées, un diff illisible, et un `dist`
+# qui ne correspond plus à ce que le bundler vient d'écrire.
+
+# Artefacts générés / build
+dist/
+public/dist/
+**/dist/**
+node_modules/
+var/
+.turbo/
+coverage/
+
+# Photos jetables (captures, journaux) — elles se refont, on ne les aligne pas.
+tmp/
+
+# Lockfiles & minifiés : ni lisibles ni à relire.
+package-lock.json
+**/*.min.js
+**/*.min.css

package/templates/app/base/prettierrc.json.tpl

@@ -0,0 +1,12 @@
+{
+  "printWidth": 80,
+  "tabWidth": 2,
+  "useTabs": false,
+  "semi": true,
+  "singleQuote": false,
+  "quoteProps": "as-needed",
+  "trailingComma": "all",
+  "bracketSpacing": true,
+  "arrowParens": "always",
+  "endOfLine": "lf"
+}

package/templates/app/base/rolldown.config.ts.tpl

@@ -0,0 +1,8 @@
+import { defineNodefonyRolldownConfig } from "nodefony/bundler";
+
+/**
+ * Build de l'app — tout le socle (preserveModules, treeshake, décorateurs lus
+ * du tsconfig) vit dans `nodefony/bundler`. `externalDeps` : le runtime vient
+ * de `node_modules`, seul TON code est bundlé.
+ */
+export default defineNodefonyRolldownConfig({ externalDeps: true });

package/templates/app/base/tests/config.test.ts.tpl

@@ -0,0 +1,29 @@
+import { describe, it, expect } from "vitest";
+import config from "../nodefony.config";
+import { env } from "../env";
+import App from "../index";
+
+/**
+ * Tests UNITAIRES — zéro serveur, zéro infra : ils valident que l'app se CHARGE.
+ *
+ * C'est le filet le moins cher qui attrape le plus d'erreurs : un import cassé,
+ * un décorateur mal appliqué, une config qui déréférence le kernel trop tôt
+ * (interdit — le kernel n'existe pas encore à l'import) font échouer CE fichier
+ * avant même de booter quoi que ce soit.
+ */
+describe("l'app se charge (imports, décorateurs, config)", () => {
+  it("le descripteur de config existe (defineConfig)", () => {
+    expect(config).toBeDefined();
+  });
+
+  it("le catalogue d'env typé existe (defineEnv — seul lecteur de process.env)", () => {
+    expect(env).toBeDefined();
+  });
+
+  it("le module App est défini et décoré (ses controllers sont attachés)", () => {
+    // @controllers([...]) WRAPPE la classe (c'est le décorateur qui attache les
+    // controllers au module) : on vérifie le constructeur, pas son nom interne.
+    expect(App).toBeTypeOf("function");
+    expect(App.prototype).toBeDefined();
+  });
+});

package/templates/app/base/tests/e2e.setup.ts.tpl

@@ -0,0 +1,181 @@
+import { execFileSync } from "node:child_process";
+<% if (!it.db) { %>import { rmSync } from "node:fs";
+import path from "node:path";
+<% } %>import { nodefonyBin, runningAppPort } from "nodefony/testing";
+/**
+ * Démarre l'application UNE fois pour toute la suite E2E, et l'arrête à la fin.
+ *
+ * Pourquoi ici et pas dans chaque fichier de test : chaque entité générée apporte
+ * son propre fichier `*.e2e.test.ts`, et un `beforeAll` par fichier signifierait
+ * un démarrage complet par fichier — la suite se paierait en minutes, et deux
+ * fichiers qui démarrent la même application se marcheraient dessus.
+ *
+ * La mécanique est 100 % native Nodefony :
+ *   - `nodefony production --detach --wait` : lancement détaché, exit 0 seulement
+ *     quand la readiness est sondée (ports ouverts) — aucun sleep arbitraire ;
+ *   - `nodefony stop` : arrêt propre de tout runtime de l'application.
+ *
+ * Les tests ne reçoivent pas le port par ce fichier : ils le lisent eux-mêmes
+ * avec `runningAppPort()`. Un port écrit en dur casse dès que l'application
+ * déclare le sien (`NF_PORT`, `PORT` en PaaS) ou qu'un port occupé l'a fait
+ * glisser — et un port de REPLI est pire encore, il fait interroger le premier
+ * serveur venu sur la machine.
+ */
+
+/**
+ * Le lanceur du framework — RÉSOLU par le framework lui-même.
+ *
+ * Aucun chemin n'est écrit ici, et c'est le point : `node_modules/.bin/nodefony`
+ * n'existe pas sous Windows (npm y écrit un `.cmd`, que Node refuse d'exécuter
+ * sans shell), et l'emplacement du paquet dépend du hoisting, des espaces de
+ * travail, du gestionnaire utilisé. `nodefonyBin()` demande à Node de localiser
+ * le paquet et lit son champ `bin` : une seule implémentation, dans le
+ * framework, qui suit ses propres déménagements.
+ *
+ * Le résultat se donne à `node`, jamais au système : c'est un script.
+ */
+const bin = nodefonyBin();
+
+/**
+ * Base de données de la suite E2E — jetable, et surtout SÉPARÉE de celle du
+ * développement.
+ *
+ * Une suite qui écrit dans la base de dev ne fait pas que la salir : elle y
+ * sème un compte `admin` dont le mot de passe est celui, écrit en clair dans ce
+ * fichier. Le seed étant idempotent, `admin` / `admin` — le couple annoncé par
+ * le `.env` et le README — cesse alors de fonctionner pour toujours, sans le
+ * moindre message. Symétriquement, un `admin` déjà semé en développement fait
+ * échouer `connexionAdmin()`, et la suite accuse la route qu'elle mesure au
+ * lieu de son décor. Un fichier à part supprime les deux pannes d'un coup, et
+ * rend la suite reproductible.
+ *
+ * Surcharge : `NF_E2E_DATABASE_URL` — pour éprouver la suite sur un AUTRE
+ * serveur que celui du développement (une instance PostgreSQL de recette, par
+ * exemple).
+ *
+ * ⚠️ **Elle ne change pas le DIALECTE de vos entités.** Elles sont écrites pour
+ * celui que vous avez choisi à la création de l'application, et l'ORM refuse de
+ * démarrer sur un autre en nommant l'entité fautive. Viser un moteur différent
+ * suppose de porter chaque entité (`createXTable("postgres")`) — un chantier,
+ * pas une variable.
+<% if (it.db) { %> *
+ * Sur <%= it.db.label %>, c'est une base À PART sur le même serveur —
+ * `<%= it.db.databaseE2e %>`, que votre décor FOURNIT : le compose généré la
+ * crée, et votre recette doit faire de même. Une suite de tests ne se fabrique
+ * pas une base : `CREATE DATABASE` est un privilège d'administration que
+ * l'utilisateur applicatif n'a pas.
+<% } %> */
+export const URL_BASE_E2E =
+<% if (it.db) { %>  process.env.NF_E2E_DATABASE_URL ?? "<%= it.db.urlE2e %>";<% } else { %>  process.env.NF_E2E_DATABASE_URL ??
+  `sqlite:${path.resolve("var/databases/e2e.db")}`;<% } %>
+<% if (it.hasSecurity) { %>
+/**
+ * Mot de passe du compte d'administration, POUR LA SUITE DE TESTS UNIQUEMENT.
+ *
+ * La suite tourne en `production`, où aucun compte n'est semé sans mot de passe
+ * explicite — c'est voulu : une application ne doit jamais naître en production
+ * avec des identifiants connus. Les tests, eux, ont besoin d'une identité pour
+ * éprouver les routes protégées (la suppression, notamment), d'où cette valeur
+ * jetable, posée dans l'environnement du serveur de test et nulle part ailleurs.
+ */
+export const MOT_DE_PASSE_ADMIN = "e2e-admin-jetable";
+
+/**
+ * Ouvre une session d'administration et rend l'en-tête `Cookie` à rejouer.
+ *
+ * C'est ainsi qu'un client réel s'authentifie auprès de l'application : un POST
+ * sur la route de connexion du framework, puis le cookie de session sur chaque
+ * requête suivante. Les tests d'une route protégée s'en servent ; les autres
+ * l'ignorent.
+ *
+ * @returns L'en-tête `Cookie` complet, à passer tel quel à `fetch`.
+ * @throws Si la connexion échoue — mieux vaut un test qui dit « je n'ai pas pu
+ * m'authentifier » qu'un test qui conclut « accès refusé » sur un décor cassé.
+ */
+export async function connexionAdmin(): Promise<string> {
+  const port = runningAppPort();
+  const res = await fetch(
+    `http://127.0.0.1:${port}/nodefony/security/api/auth/login`,
+    {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({
+        username: "admin",
+        password: MOT_DE_PASSE_ADMIN,
+      }),
+    },
+  );
+  if (res.status !== 200) {
+    throw new Error(
+      `connexion admin impossible (${res.status}) — le décor de test, pas la route mesurée`,
+    );
+  }
+  const cookies = res.headers.getSetCookie?.() ?? [];
+  return cookies.map((c) => c.split(";")[0]).join("; ");
+}
+<% } %>
+export async function setup(): Promise<void> {
+  // Repartir d'une base VIERGE : une suite dont le verdict dépend de ce qu'un
+  // run précédent a laissé n'est pas reproductible.
+<% if (it.db) { %>  //
+  // Sur un moteur serveur, une base ne s'EFFACE pas — on retire ses tables.
+  // `orm:reset` est le geste que le framework prévoit pour ça, et il n'existe
+  // qu'en développement : cette base-ci n'a pas d'autre usage que la suite.
+  execFileSync(process.execPath, [bin, "orm:reset", "--yes"], {
+    stdio: "inherit",
+    timeout: 120_000,
+    env: {
+      ...process.env,
+      NODE_ENV: "development",
+      NF_DATABASE_URL: URL_BASE_E2E,
+    },
+  });
+<% } else { %>  // Les compagnons `-wal` et `-shm` partent avec le fichier, sinon SQLite
+  // ressuscite l'état d'avant.
+  if (URL_BASE_E2E.startsWith("sqlite:")) {
+    const fichier = URL_BASE_E2E.slice("sqlite:".length);
+    for (const suffixe of ["", "-wal", "-shm"]) {
+      rmSync(`${fichier}${suffixe}`, { force: true });
+    }
+  }
+<% } %>
+<% if (it.hasOrm) { %>  // Le schéma AVANT le trafic — le patron de production, appliqué ici tel quel.
+  //
+  // En production le démarrage ne fabrique JAMAIS le schéma (mode `ddl: none`) :
+  // c'est délibéré, parce que plusieurs exemplaires partent en même temps et
+  // qu'aucun d'eux ne doit toucher aux tables. C'est un travail d'orchestrateur,
+  // qui passe AVANT. Sans cette étape, la base qu'on vient d'effacer reste vide,
+  // la mise en service est retenue (`/readyz` rend 503), et `--wait` attend une
+  // disponibilité qui ne viendra jamais.
+  execFileSync(process.execPath, [bin, "orm:migrate"], {
+    stdio: "inherit",
+    timeout: 120_000,
+    env: {
+      ...process.env,
+      NODE_ENV: "production",
+      NF_DATABASE_URL: URL_BASE_E2E,
+    },
+  });
+<% } %>  execFileSync(process.execPath, [bin, "production", "--detach", "--wait"], {
+    stdio: "inherit",
+    timeout: 120_000,
+    env: {
+      ...process.env,
+      // La suite ne touche JAMAIS la base de développement — cf `URL_BASE_E2E`.
+      NF_DATABASE_URL: URL_BASE_E2E,
+<% if (it.hasSecurity) { %>      // Sans cette variable, la production ne sème AUCUN compte : les tests des
+      // routes protégées n'auraient aucune identité à présenter, et échoueraient
+      // en accusant la garde plutôt que le décor.
+      NF_ADMIN_PASSWORD: MOT_DE_PASSE_ADMIN,
+<% } %>    },
+  });
+}
+
+export async function teardown(): Promise<void> {
+  // Jamais de serveur laissé derrière : un runtime orphelin tient les ports et
+  // fait échouer le run suivant sur une erreur qui ne parle pas de lui.
+  execFileSync(process.execPath, [bin, "stop"], {
+    stdio: "inherit",
+    timeout: 30_000,
+  });
+}

package/templates/app/base/tests/e2e.test.ts.tpl

@@ -0,0 +1,105 @@
+import { runningAppPort } from "nodefony/testing";
+import { readRuntimeState } from "nodefony";
+<% if (it.complete) { %>// La façade temps réel isomorphe — côté Node, subpath `nodefony/client`.
+import { RealtimeClient } from "nodefony/client";
+<% } %>import { describe, it, expect, beforeAll } from "vitest";
+
+/**
+ * Test E2E — parle en HTTP + WebSocket à l'application RÉELLE (mode production).
+ *
+ * Seule porte d'entrée : `npm run test:e2e` (build d'abord : un serveur spawné
+ * valide le DIST, pas le source). Ce fichier est EXCLU de `vitest.config.ts` et
+ * ciblé par `vitest.e2e.config.ts` — invoqué, il tourne TOUJOURS : pas de gate
+ * d'environnement qui l'afficherait « skipped » dans un rapport vert.
+ *
+ * Le démarrage et l'arrêt de l'application vivent dans `tests/e2e.setup.ts`
+ * (une fois pour toute la suite), pas ici.
+ * Client WebSocket = `WebSocket` NATIF Node (≥ 22) — zéro dépendance de test.
+ *
+ * Le port n'est PAS écrit en dur : le serveur publie ses ports effectifs
+ * (`runningAppPort`) — un test qui suppose 5151 casse dès que l'app déclare son
+ * port (`NF_PORT`, `PORT` en PaaS) ou qu'un port occupé l'a fait glisser en dev.
+ */
+let BASE = "http://127.0.0.1:5151";
+let WS_BASE = "ws://127.0.0.1:5151";
+
+describe("e2e — l'app boote et répond (HTTP + WS)", () => {
+  beforeAll(() => {
+    // Le serveur est PRÊT (le setup global n'est sorti qu'après la readiness) :
+    // ses ports sont publiés. Le premier est celui du serveur en clair (une app
+    // TLS-only adaptera ces deux lignes).
+    const port = runningAppPort();
+    BASE = `http://127.0.0.1:${port}`;
+    WS_BASE = `ws://127.0.0.1:${port}`;
+  });
+
+  it("GET /api/hello → 200 + payload JSON", async () => {
+    const res = await fetch(`${BASE}/api/hello`);
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as { hello: string; pid: number };
+    expect(body.hello).toBe("<%= it.appName %>");
+    expect(body.pid).toBeGreaterThan(0);
+  });
+
+  it("WS /api/echo → echo du message (même controller que le HTTP)", async () => {
+    const ws = new WebSocket(`${WS_BASE}/api/echo`);
+    const echoed = await new Promise<unknown>((resolve, reject) => {
+      const timer = setTimeout(
+        () => reject(new Error("timeout WS 10s")),
+        10_000,
+      );
+      ws.addEventListener("open", () => ws.send("ping-e2e"));
+      ws.addEventListener("message", (event) => {
+        const data = JSON.parse(String(event.data)) as { echo?: string };
+        // Le handshake du controller peut répondre d'abord — on attend l'echo.
+        if (data.echo !== undefined) {
+          clearTimeout(timer);
+          resolve(data);
+        }
+      });
+      ws.addEventListener("error", () => reject(new Error("erreur WS")));
+    });
+    ws.close();
+    expect(echoed).toEqual({ echo: "ping-e2e" });
+  });
+
+  it("probe cloud-native /livez → 200 (celle qu'interroge k8s)", async () => {
+    const res = await fetch(`${BASE}/livez`);
+    expect(res.status).toBe(200);
+  });
+<% if (it.complete) { %>
+  it("realtime — RPC live:ping + aller-retour sur le canal live:events", async () => {
+    // La MÊME façade que les vitrines navigateur — zéro `ws` à la main.
+    const live = new RealtimeClient({ url: `${WS_BASE}/api/live/realtime` });
+    try {
+      // Listener posé AVANT subscribe : le fournisseur démarre au 1ᵉʳ abonné.
+      const receivedP = new Promise<unknown>((resolve, reject) => {
+        const timer = setTimeout(
+          () => reject(new Error("timeout canal 10s")),
+          10_000,
+        );
+        live.on("live:events", (msg) => {
+          clearTimeout(timer);
+          resolve(msg);
+        });
+      });
+      await live.connect();
+      // Action OUVERTE ({ authenticated: false }) — répond même anonyme.
+      const pong = (await live.request("live:ping", {})) as { pong: boolean };
+      expect(pong.pong).toBe(true);
+      // Canal libre. Il ne bat PAS tout seul : il parle quand il se passe
+      // quelque chose — ici, ce que cette connexion envoie et que toutes
+      // reçoivent. C'est ce partage qui fait l'intérêt d'une socket, pas un
+      // battement qui coûterait une trame par seconde et par client.
+      live.subscribe("live:events");
+      live.emit("live:say", { text: "bonjour e2e" });
+      const received = (await receivedP) as { text: string; pid: number };
+      expect(received.text).toBe("bonjour e2e");
+      expect(received.pid).toBeGreaterThan(0);
+    } finally {
+      // Le nettoyage vit dans le `finally` : une assertion qui tombe ne doit
+      // jamais laisser une socket ouverte derrière le run.
+      live.disconnect();
+    }
+  }, 15_000);
+<% } %>});