nodefony 7.0.2 → 10.0.0-alpha.2

package/docs/testing.md

@@ -0,0 +1,203 @@
+---
+title: "Éprouver une application — le harnais livré avec le framework"
+navTitle: Tests
+lang: fr
+module: "@nodefony/core"
+topic: testing
+coverageModule: nodefony-core
+coveragePackage: "nodefony (cœur)"
+coverageFiles: "testing/index.ts"
+section: "Cœur runtime"
+audience: [developer]
+tags: [tests, e2e, testing, harnais, vitest, unitaire, integration]
+version: "doc"
+status: stable
+updated: 2026-09-01
+source: "src/nodefony/docs/testing.md"
+---
+
+# Éprouver une application Nodefony
+
+> Une application créée par `nodefony create app` naît avec des tests qui marchent : un harnais
+> qui démarre le serveur une fois pour toute la suite, l'arrête à la fin, et donne aux tests le
+> moyen de savoir à qui parler. Cette page explique ce que ce harnais utilise — le sous-chemin
+> `nodefony/testing` — et comment vous en écrivez un second.
+
+📍 [Documentation](../../../docs/index.md) › [Cœur — @nodefony/core](index.md) › **Tests**
+
+## Le modèle — trois niveaux, trois outils
+
+Trois questions différentes, qu'il ne faut pas confondre :
+
+| Ce que vous voulez éprouver                          | Ce qu'il vous faut                                |
+| ---------------------------------------------------- | ------------------------------------------------- |
+| La logique d'**un service**, seule                   | `createTestModule()` — aucun serveur, aucun port  |
+| Le comportement de **l'application qui tourne**      | le harnais généré + `runningAppPort()`            |
+| Ce qui ne s'observe qu'**au démarrage** d'un process | `startSpareApp()` — un exemplaire jetable, à part |
+
+Le point commun : **rien de tout cela ne demande de fabriquer un kernel à la main**. Un service
+Nodefony reçoit un `Module`, et un `Module` réclame normalement un `Kernel` — sans porte d'entrée,
+éprouver un calcul de taxe obligerait à démarrer une application entière, ou à écrire un
+`as unknown as Kernel` que les règles du projet interdisent. C'est ce trou que le sous-chemin
+`nodefony/testing` comble.
+
+## 🚀 Démarrage rapide
+
+```ts
+import { createTestModule, runningAppPort } from "nodefony/testing";
+
+// 1. Un module JETABLE : il porte un conteneur et un bus d'événements, rien d'autre.
+//    De quoi construire un service seul, sans démarrer quoi que ce soit.
+const app = createTestModule();
+
+// 2. Les services se donnent leurs dépendances À LA MAIN — c'est ce qui permet
+//    d'y glisser un double.
+class TaxService {
+  rate = 0.2;
+}
+class InvoiceService {
+  constructor(
+    readonly module: typeof app,
+    readonly tax: TaxService,
+  ) {}
+  total(ht: number): number {
+    return ht * (1 + this.tax.rate);
+  }
+}
+const invoice = new InvoiceService(app, new TaxService());
+console.log(invoice.total(100)); // 120
+
+// 3. Dans un test de bout en bout, le port ne s'écrit JAMAIS en dur :
+//    il se demande à l'application qui tourne.
+const port = runningAppPort();
+const res = await fetch(`http://127.0.0.1:${port}/`);
+console.log(res.status);
+```
+
+## Ce que le sous-chemin fournit
+
+<!-- prettier-ignore -->
+| Export | Ce qu'il fait | Quand s'en servir |
+| --- | --- | --- |
+| `createTestModule()` (`testing/index.ts:160`) | Rend un `Module` jetable portant un conteneur et un bus d'événements | Test unitaire d'un service |
+| `runningAppPort()` (`testing/index.ts:96`) | Lit le port de l'application démarrée par le décor | Tout test de bout en bout |
+| `startSpareApp()` (`testing/index.ts:251`) | Démarre un exemplaire jetable dans un état choisi, puis restaure l'état d'exécution | Éprouver un démarrage, pas un fonctionnement |
+| `nodefonyBin()` (`testing/index.ts:64`) | Résout le lanceur du framework, où qu'il soit installé | Appeler une commande depuis un script |
+
+### `createTestModule()` — et ce qu'il ne fait pas
+
+Il ne démarre aucun kernel, n'ouvre aucun port, ne lit aucune configuration. Conséquence directe,
+et qui surprend : **la résolution par le conteneur n'est pas de la partie**. `@inject("XService")`
+passe par le singleton du kernel, qui n'existe pas ici.
+
+```ts ignore
+const app = createTestModule();
+const invoice = new InvoiceService(app, new TaxService(app)); // ✅
+const invoice = await app.addService(InvoiceService); // ❌ exige un kernel vivant
+```
+
+Ce n'est pas une limite gênante : un test unitaire **donne lui-même** la dépendance, ce qui est
+précisément l'intérêt de l'injection par constructeur — et ce qui permet d'y glisser un double.
+
+### `runningAppPort()` — pourquoi il lève plutôt que de se rabattre
+
+Il lit l'état d'exécution publié par l'application démarrée, et **échoue franchement** s'il ne
+trouve pas de port. Un port de repli ferait interroger un serveur étranger sur la même machine, et
+le verdict porterait sur lui : un test vert qui n'a rien mesuré de votre code.
+
+## Le harnais généré — `tests/e2e.setup.ts`
+
+Chaque application créée par `nodefony create app` reçoit ce fichier. Il fait quatre choses, dans
+cet ordre, **une fois pour toute la suite** :
+
+1. **Repartir d'une base vierge.** Un verdict qui dépend de ce qu'un essai précédent a laissé n'est
+   pas reproductible. Sur SQLite le fichier est supprimé — avec ses compagnons `-wal` et `-shm`,
+   sans quoi la base ressuscite. Sur un moteur serveur, c'est `orm:reset` : une base ne s'efface
+   pas, on retire ses tables.
+2. **Appliquer le schéma avant le trafic** (`orm:migrate`). C'est le patron de production tel quel :
+   en production le démarrage ne fabrique jamais le schéma, parce que plusieurs exemplaires partent
+   en même temps et qu'aucun ne doit toucher aux tables.
+3. **Démarrer l'application** par `production --detach --wait` : la commande ne rend la main que
+   lorsque la disponibilité est constatée — aucune attente arbitraire.
+4. **L'arrêter à la fin** (`stop`), sans exception : un serveur orphelin tient les ports et fait
+   échouer l'essai suivant sur une erreur qui ne parle pas de lui.
+
+Le fichier expose aussi `URL_BASE_E2E` — une base **séparée de celle du développement**, ce qui
+n'est pas une coquetterie : une suite qui écrit dans la base de développement y sème un compte
+`admin` dont le mot de passe est celui du fichier de test, et le couple annoncé par le README cesse
+alors de fonctionner sans le moindre message. Surcharge possible par `NF_E2E_DATABASE_URL`.
+
+> Cette variable ne change **pas le dialecte** de vos entités : elles sont écrites pour le moteur
+> choisi à la création, et l'ORM refuse de démarrer sur un autre en nommant l'entité fautive.
+
+## Écrire un second harnais — un exemplaire jetable
+
+Certaines choses ne s'observent que sur un processus qui **démarre** dans un état précis : un
+schéma en retard qui retient la mise en service, une dépendance absente, un refus de démarrage. Le
+décor de la suite, lui, a démarré l'application dans l'état normal — et c'est ce qu'on veut.
+
+```ts ignore
+const jetable = await startSpareApp({
+  port: 5399,
+  env: { NODE_ENV: "production", NF_DATABASE_URL: "sqlite:/tmp/vierge.db" },
+});
+try {
+  const res = await fetch(`http://127.0.0.1:${jetable.port}/readyz`);
+  assert.equal(res.status, 503);
+} finally {
+  await jetable.stop();
+}
+```
+
+Le port est **imposé, jamais deviné** : l'exemplaire du décor tient déjà celui de l'application, et
+la sonde doit savoir à qui elle parle.
+
+## 📖 Lexique
+
+| Terme                  | Ce que c'est                                                                                                                      |
+| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
+| **Sous-chemin**        | Une porte d'entrée secondaire d'un paquet (`nodefony/testing` à côté de `nodefony`), déclarée dans son `package.json`.            |
+| **e2e**                | _End to end_ — un test qui exerce la chaîne entière, du client à la base réelle, sans rien simuler.                               |
+| **Module jetable**     | Ce que rend `createTestModule()` : un porteur de conteneur et d'événements, sans kernel, sans port, sans configuration.           |
+| **État d'exécution**   | Le fichier où une application publie ses ports en démarrant. C'est lui que `runningAppPort()` lit — un seul par racine de projet. |
+| **Exemplaire jetable** | Un second process de la même application, sur un autre port, démarré pour observer un cas de démarrage précis.                    |
+
+## ⚠️ Pièges
+
+- **Deux exemplaires lancés depuis le même dossier partagent un seul état d'exécution.** Le second
+  écrase les ports du premier, et `runningAppPort()` se met à désigner le jetable — puis à lever
+  une fois qu'il est mort. Le défaut ne se voit pas dans le test qui l'a créé : il tombe sur le
+  **suivant**, et accuse une route qui n'a rien fait. C'est pour cela que `stop()` restaure l'état
+  d'avant, et pourquoi il doit être appelé dans un `finally`.
+- **Un port écrit en dur casse dès que l'application déclare le sien** (`NF_PORT`, ou la variable
+  qu'un hébergeur impose), ou qu'un port occupé l'a fait glisser.
+- **`createTestModule()` ne résout rien par le conteneur.** Si un test échoue sur
+  `module.container` au constructeur, c'est qu'une dépendance a été demandée à l'injecteur au lieu
+  d'être donnée à la main.
+- **Une suite lancée ailleurs qu'à la racine de l'application ne trouve pas l'état d'exécution**,
+  et `runningAppPort()` lève en le disant.
+- **La suite tourne en `production`**, où aucun compte n'est semé sans mot de passe explicite. Les
+  routes protégées ont donc besoin de l'identité que le harnais pose lui-même — sans elle, elles
+  échouent en accusant la garde plutôt que le décor.
+
+## 🧪 Tests & couverture
+
+Les chiffres exacts vivent dans la carte de l'aperçu, régénérée en comptant — jamais figés ici.
+
+<!-- prettier-ignore -->
+| Type | Où | Ce qui est prouvé |
+| --- | --- | --- |
+| Unitaires | `nodefony` `testing.test.ts` | ce que rend le module jetable, la lecture du port, la restauration de l'état d'exécution |
+| Unitaires (génération) | `nodefony` `create.test.ts` | que le harnais est bien livré avec l'application créée, dans ses quatre variantes |
+
+## 🔗 Pour aller plus loin
+
+- ⬆️ **Retour au hub** : [Cœur — @nodefony/core](index.md) ·
+  [Toute la documentation](../../../docs/index.md)
+- 🏗️ **Ce qui a généré ces fichiers** :
+  [`generer-du-code.md`](../../../docs/guides/generer-du-code.md)
+- 🗄️ **La base que la suite efface** :
+  [`persistence.md`](../../../docs/guides/persistence.md)
+- 🖥️ **Les commandes que le harnais appelle** : [la CLI](cli.md)
+- 🏭 **Ce que la forge du framework lance, et pourquoi un saut compte comme un succès** :
+  [`integration-continue.md`](../../../docs/guides/integration-continue.md)

package/docs/vue-composables.md

@@ -0,0 +1,255 @@
+---
+title: "Composables Vue — nodefony/vue"
+lang: fr
+module: "@nodefony/core"
+topic: vue-composables
+coverageModule: nodefony-core
+coveragePackage: "nodefony (cœur)"
+coverageFiles: "client/vue/index.ts,client/realtime/observe.ts"
+section: "Cœur runtime"
+audience: [developer]
+tags:
+  [
+    vue,
+    composables,
+    plugin,
+    temps-reel,
+    websocket,
+    abonnement,
+    portee,
+    identite,
+    isomorphe,
+  ]
+version: "doc"
+status: stable
+updated: 2026-08-27
+source: "src/nodefony/docs/vue-composables.md"
+---
+
+# Composables Vue — `nodefony/vue`
+
+> Le subpath `nodefony/vue` branche un composant Vue 3 sur la socket Nodefony **sans une ligne de
+> glue** : un plugin installé sur l'application, puis des composables ciblés qui s'abonnent au
+> `setup` et rendent l'abonnement à la mort de la portée. Ils ne gèrent **que** l'abonnement —
+> ouvrir et maintenir la connexion reste le travail du client, décrit dans
+> [Client isomorphe](client.md). Le pendant exact de [Hooks React](react-hooks.md) : même surface,
+> mêmes noms, mêmes garanties. Ancré sur `src/nodefony/src/client/vue/index.ts`.
+
+📍 [Documentation](../../../docs/index.md) › [Cœur — @nodefony/core](index.md) › **Composables Vue**
+
+## 🧠 Le modèle mental — une prise, N composants branchés dessus
+
+Un composant vit et meurt au gré de la navigation. Une socket, elle, doit rester ouverte. La liaison
+tient les deux bouts : **le fil est unique et long**, **les branchements sont nombreux et courts**.
+
+```mermaid
+flowchart LR
+  APP["main.ts<br/>app.use(nodefonyVue, { url }) — UNE fois"] --> CL
+  subgraph CL["RealtimeClient (hors Vue)"]
+    direction TB
+    S["état · identité · notices"]
+    R["abonnements ref-comptés<br/>canal → nb de consommateurs"]
+  end
+  CL --> P["provide/inject<br/>markRaw — jamais réactif"]
+  P --> H1["useNodefonyState()<br/>Ref&lt;RealtimeState&gt;"]
+  P --> H2["useNodefonyChannelData()<br/>Ref&lt;T | null&gt;"]
+  P --> H3["useNodefonyChannel()<br/>un rappel, rien à afficher"]
+  H1 -. "fin de portée" .-> R
+  H2 -. "fin de portée" .-> R
+  H3 -. "fin de portée" .-> R
+```
+
+## 📖 Lexique
+
+| Terme                  | Ce que c'est ici                                                                                         |
+| ---------------------- | -------------------------------------------------------------------------------------------------------- |
+| **composable**         | Une fonction appelée dans un `setup` qui installe des effets et rend de l'état réactif. L'idiome de Vue. |
+| **plugin**             | Ce qu'on installe sur l'application (`app.use`). C'est là que vit une politique, en Vue.                 |
+| **portée d'effet**     | Le contexte qui possède les effets d'un composant. Sa mort libère tout ce qui y a été enregistré.        |
+| **`Ref<T>`**           | Une boîte réactive : on lit et on écrit `.value`, et le rendu suit.                                      |
+| **`MaybeRefOrGetter`** | « une valeur, une `ref`, ou une fonction qui la calcule » — ce qui rend un argument réactif sans effort. |
+
+## Pourquoi un plugin, et pas un composant enveloppant
+
+React publie un `<NodefonyProvider>` parce qu'en React tout est composant. En Vue, une politique qui
+vaut pour l'application entière s'installe sur l'application :
+
+```ts
+createApp(App).use(nodefonyVue, { url: "/api/live/realtime" }).mount("#app");
+```
+
+Traduire littéralement le fournisseur React aurait donné un composant de plus dans l'arbre, que
+personne n'aurait pensé à chercher. **Une liaison idiomatique n'est pas une traduction mot à mot :
+c'est la même garantie, dite dans la langue du framework.**
+
+## Les trois règles que Vue impose, et que React ne montre pas
+
+1. **Le client n'entre jamais dans un `ref()`.** Il serait enveloppé dans un proxy réactif profond :
+   ses égalités de référence internes casseraient, et chaque accès paierait une interception — pour
+   une réactivité dont il n'a aucun besoin, ses changements passant par ses propres `on*`. Le plugin
+   le pose `markRaw` (`src/nodefony/src/client/vue/index.ts:155`), et un test le vérifie
+   (`isReactive(useNodefony()) === false`).
+2. **La libération passe par `onScopeDispose`**, jamais par `onUnmounted` seul : c'est le seul des
+   deux qui couvre aussi une portée créée hors composant (`effectScope()`). Un abonnement qui fuit
+   **ne se voit pas à l'écran** — la page affiche ce qu'il faut, et le serveur pousse un canal que
+   plus personne ne regarde. Le motif commun à tous les composables est unique
+   (`src/nodefony/src/client/vue/index.ts:217`) : brancher, rebrancher quand la source change,
+   libérer à la mort de la portée.
+3. **Un composable appelé hors portée lève** (`src/nodefony/src/client/vue/index.ts:199`), plutôt
+   que de fuir en silence. Le message dit le remède : envelopper l'appel dans `effectScope()`.
+
+## 🚀 Démarrage rapide
+
+### 1. Le plugin, sur l'application
+
+```ts
+// frontend/src/main.ts
+import { createApp } from "vue";
+import { nodefonyVue } from "nodefony/vue";
+import App from "./App.vue";
+
+const el = document.getElementById("app");
+if (!el) throw new Error("#app not found");
+createApp(App).use(nodefonyVue, { url: "/api/live/realtime" }).mount(el);
+```
+
+L'adresse est écrite **ici, et nulle part ailleurs**. Le framework n'en devine aucune : une adresse
+devinée marche en développement et se trompe en production. Sans `url` ni `client`, le plugin refuse
+(`src/nodefony/src/client/realtime/observe.ts:126`).
+
+### 2. La page
+
+```vue
+<script setup lang="ts">
+import {
+  useNodefony,
+  useNodefonyChannelData,
+  useNodefonyState,
+} from "nodefony/vue";
+
+interface LiveEvent {
+  text: string;
+  ts: number;
+}
+
+const live = useNodefony();
+const state = useNodefonyState();
+const last = useNodefonyChannelData<LiveEvent>("live:events");
+
+const say = (text: string): void => live.emit("live:say", { text });
+</script>
+
+<template>
+  <p>connexion : {{ state }}</p>
+  <p v-if="last">{{ last.text }}</p>
+  <button @click="say('bonjour')">envoyer</button>
+</template>
+```
+
+Il n'y a **rien à libérer** : la portée du composant rend les abonnements à sa mort. C'est la
+différence visible avec un câblage à la main, où il fallait tenir une liste de fonctions de
+libération et n'en oublier aucune.
+
+### 3. Quand l'application possède son cycle de connexion
+
+```ts
+// La socket fournie l'emporte sur `url`, et son cycle n'est pas touché :
+// ni `connect`, ni `disconnect`.
+app.use(nodefonyVue, { client: maSocket });
+```
+
+### 4. Un canal qui change
+
+```ts
+const salle = ref("salon:general");
+// L'abonnement SUIT la valeur : l'ancien canal est rendu avant que le
+// nouveau soit pris. Aucun tableau de dépendances à tenir.
+const messages = useNodefonyChannelData<Message>(() => salle.value);
+```
+
+## 🧰 Les composables
+
+Tous rendent une `Ref` en lecture — on lit `.value` (ou rien du tout dans un template, Vue
+déballe). La socket, elle, n'est pas réactive : c'est un objet, pas un état.
+
+| Composable                             | Rend                            | À quoi ça sert                                               |
+| -------------------------------------- | ------------------------------- | ------------------------------------------------------------ |
+| `nodefonyVue`                          | —                               | le plugin : fournit la socket et lance la connexion          |
+| `useNodefony()`                        | `RealtimeClient`                | l'échappatoire : `emit`, `request`, `mutate`, `ping`         |
+| `useNodefonyState()`                   | `Ref<RealtimeState>`            | afficher l'état, griser un bouton pendant une reconnexion    |
+| `useNodefonyIdentity()`                | `Ref<RealtimeIdentity \| null>` | savoir qui est connecté — sans appeler `/auth/me`            |
+| `useNodefonyChannel(canal, onMessage)` | —                               | réagir à chaque message (journal, son, animation)            |
+| `useNodefonyChannelData<T>(canal)`     | `Ref<T \| null>`                | la dernière valeur — le cas le plus courant                  |
+| `useNodefonyAdaptiveChannel(…)`        | `Ref<number>`                   | même chose, en cadence auto-ajustée ; rend la cadence        |
+| `useNodefonyAdaptiveChannelData<T>(…)` | `{ data, intervalMs }`          | la dernière valeur **et** la cadence                         |
+| `useNodefonyChannelStats(canal)`       | `Ref<MessageStats \| null>`     | débit et série d'un canal, pour un VU-mètre                  |
+| `useNodefonySnapshot()`                | `Ref<SocketSnapshot \| null>`   | ce que la socket sait d'elle-même : canaux, trames, dernière |
+| `useNodefonySyslog(opts?)`             | `Ref<unknown[]>`                | le flux de journal, anneau borné et filtre de sévérité       |
+| `useNodefonyNotifications(onNotice)`   | —                               | les notices normalisées — à monter **une seule fois**        |
+| `useNodefonyNoticeLog(opts?)`          | `Ref<NodefonyNotice[]>`         | l'historique borné des incidents                             |
+
+La déclaration de chacun se lit dans `src/nodefony/src/client/vue/index.ts:179` et suivantes.
+
+Sont aussi réexportés depuis ce subpath : `rateChannel`, `parseRate`, `isRateChannel` (fabriquer un
+nom de canal cadencé), et les types `RealtimeIdentity`, `RealtimeState`, `NodefonyNotice`,
+`SocketSnapshot` — pour qu'un composant puisse **nommer** ce qu'il reçoit.
+
+Les arguments « canal » et « cadence » acceptent une valeur, une `ref` ou une fonction : l'abonnement
+suit, sans liste de dépendances.
+
+## 🏗️ Cycle de vie d'un abonnement
+
+```
+setup()            → subscribe (si premier consommateur du canal)
+message reçu       → .value change → le rendu suit
+canal qui change   → unsubscribe de l'ancien, subscribe du nouveau
+reconnexion        → le client rejoue TOUS les abonnements, sans rien à faire
+fin de portée      → unsubscribe (si dernier consommateur)
+```
+
+Ce qui est **partagé** et ne dépend pas de Vue — le comptage de références, le rejeu après
+reconnexion, l'appariement `on`↔`subscribe` — vit dans le socle agnostique et est prouvé une fois
+pour les quatre fronts. Ce qui est **propre à Vue** — la portée, la réactivité, la non-réactivité du
+client — est prouvé dans `src/nodefony/src/tests/clientVue.test.ts:1`.
+
+La socket, elle, **n'est jamais coupée par un composant**. Elle appartient à la page : la fermer au
+démontage trancherait les requêtes en vol des autres consommateurs.
+
+## ⚠️ Pièges (symptôme → cause → correction)
+
+| Symptôme                                                     | Cause                                                                  | Correction                                                                    |
+| ------------------------------------------------------------ | ---------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
+| `useNodefony() : le plugin n'est pas installé`               | Le composable est appelé hors d'une application où `app.use` a eu lieu | Installer `nodefonyVue` dans `main.ts`                                        |
+| `… doit être appelé dans un composant (setup) ou une portée` | Appel au niveau d'un module, dans un `setTimeout` ou un gestionnaire   | Appeler au `setup`, ou envelopper dans `effectScope()`                        |
+| Le plugin lève à l'installation                              | Ni `url` ni `client` fourni — le framework ne devine aucune adresse    | Passer l'URL du serveur temps réel                                            |
+| Rien n'arrive et l'état reste `disconnected`                 | Le serveur n'écoute pas cette adresse, ou la socket a été coupée       | Vérifier l'adresse du plugin, et qu'aucun code n'appelle `disconnect()`       |
+| `Module 'nodefony' has no exported member 'RealtimeClient'`  | Condition d'export `browser` inactive dans le `tsconfig.json` de l'app | Importer depuis `nodefony/client`, ou ajouter `customConditions: ["browser"]` |
+| Le canal se ré-abonne à chaque frappe                        | Le nom du canal est recalculé à chaque rendu par une fonction          | Ne faire dépendre le getter que de ce qui doit vraiment ré-abonner            |
+| Un objet du client semble « ne pas réagir »                  | Il est `markRaw` — c'est voulu                                         | Lire l'état par les composables, pas sur l'objet                              |
+| Notices en double                                            | `useNodefonyNotifications` appelé dans plusieurs composants            | Un seul appel, au shell de l'application                                      |
+| Une exception dans un rappel disparaît sans trace            | Le dispatch du client isole les erreurs de handler                     | Envelopper le corps du rappel dans son propre `try`/`catch`                   |
+
+## 🧪 Tests & couverture
+
+- **Les règles du temps réel** (comptage de références, rejeu après reconnexion, dernier reçu gagne,
+  anneaux, filtres) sont prouvées **une fois pour les quatre fronts** dans
+  `src/nodefony/src/tests/clientObserve.test.ts`. Les rejouer à travers Vue mesurerait le socle.
+- **La traduction Vue** est prouvée dans `src/nodefony/src/tests/clientVue.test.ts` : portée exigée,
+  client non réactif, canal réactif qui déplace l'abonnement, et surtout **le démontage qui rend
+  l'abonnement au serveur** — compté sur les trames émises, seul juge d'une fuite.
+- **La surface publiée** est tenue par `clientSubpathSurface.types.test.ts` : ce que les composables
+  rendent doit pouvoir être **nommé** par un consommateur, et les trois subpaths parlent des mêmes
+  types, pas de jumeaux.
+- **Aucun test de rendu** ne monte de composant réel : le harnais utilise `app.runWithContext` et
+  `effectScope`, qui donnent exactement ce qu'un composant donne à un composable, sans DOM.
+
+Couverture : `npm run coverage` dans `src/nodefony`.
+
+## 🔗 Pour aller plus loin
+
+- ⬆️ **Retour au hub** : [@nodefony/core — vue d'ensemble](index.md) · [Toute la documentation](../../../docs/index.md)
+- 🧭 **Pages sœurs** : [Client isomorphe](client.md) — la socket, le transport, la reconnexion, les
+  rôles · [Hooks React](react-hooks.md) — la même surface, en React · [Journalisation](syslog.md)
+- Le vocabulaire commun aux deux bords du fil → [Vocabulaire de la socket](../../packages/@nodefony/realtime/docs/vocabulaire.md)
+- Le module serveur qui pousse les canaux → [@nodefony/realtime](../../packages/@nodefony/realtime/docs/index.md)
+- Qui sert et reconstruit ton interface → [@nodefony/frontend](../../packages/@nodefony/frontend/docs/index.md)

package/man/nodefony.1

@@ -0,0 +1,152 @@
+.TH NODEFONY 1 "" "nodefony 10.0.0\-alpha.2" "Nodefony Manual"
+.SH NAME
+nodefony \- framework fullstack Node.js : HTTP, WebSocket, ORM, agents
+.SH SYNOPSIS
+.B nodefony
+[\fICOMMANDE\fR] [\fIOPTIONS\fR]
+.br
+.B nodefony
+\fB\-\-help\fR | \fB\-\-version\fR
+.SH DESCRIPTION
+Interface en ligne de commande de Nodefony : elle lance l'application
+(développement, production, cluster), la construit, l'inspecte et la
+diagnostique, et engendre du code conforme au framework.
+.PP
+Lancée sans argument dans un terminal interactif, elle ouvre un menu des
+gestes utiles ici. Hors terminal, elle affiche l'aide.
+.PP
+\fBCette page ne liste que les commandes du FRAMEWORK.\fR Une application en
+ajoute par ses modules \- par exemple \fBhttp:network\fR, \fBfrontend:build\fR
+ou \fBsecurity:user:add\fR \- et celles\-ci dépendent du projet dans lequel
+la commande est lancée. Pour la liste RÉELLE, dans le projet courant :
+.PP
+.RS 4
+.B nodefony \-\-help
+.RE
+.SH COMMANDS
+Les commandes sont rangées par INTENTION, dans l'ordre d'une journée de
+travail \- comme \fBnodefony \-\-help\fR. Un rangement alphabétique mettrait
+\fBai:mcp\fR avant \fBdevelopment\fR ; il ne répond à personne.
+.SS LANCER
+.TP
+.B development, dev
+démarre en développement, rechargement automatique
+.TP
+.B production, prod, start
+démarre en production, au premier plan
+.TP
+.B cluster
+démarre N workers isolés, relancés s'ils tombent
+.TP
+.B status
+dit quels processus de ce projet tournent, et où
+.TP
+.B stop
+arrête les processus Nodefony de ce projet
+.SS COMPRENDRE
+.TP
+.B card, devkit:card
+carte de visite : où l'on est, quoi lancer
+.TP
+.B doctor
+ce qui ne va pas dans cette application
+.TP
+.B inspect
+l'état réel de l'app : routes, services, config
+.TP
+.B env
+les variables d'environnement et leur provenance
+.TP
+.B symbols
+où un symbole est défini, et de qui il hérite
+.TP
+.B menu
+menu interactif : les commandes utiles ici
+.SS GÉNÉRER ET CONSTRUIRE
+.TP
+.B create
+engendre une application, un module, une entité…
+.TP
+.B build, compile
+compile les modules puis l'application vers dist/
+.TP
+.B install
+installe les dépendances puis construit le projet
+.TP
+.B outdated
+les dépendances en retard, groupées par paquet
+.SS AGENTS ET OUTILLAGE
+.TP
+.B ai:mcp
+déclare le serveur MCP de l'app à ton agent
+.TP
+.B ai:sync
+installe les skills d'agent des paquets présents
+.TP
+.B completion
+script de complétion du shell (bash | zsh | fish)
+.TP
+.B git:hooks
+pose les hooks git : contrôles au commit et au push
+.SH OPTIONS
+Options acceptées par toutes les commandes. Chaque commande porte en plus les
+siennes, que \fBnodefony \fI<commande>\fB \-\-help\fR détaille.
+.TP
+.B \-i
+.TP
+.B \-\-interactive
+.TP
+.B \-d
+.TP
+.B \-\-debug
+.TP
+.B \-v
+.TP
+.B \-\-version
+.SH ENVIRONMENT
+.TP
+.B NODE_ENV
+Mode d'exécution (development | production). Posé par l'orchestrateur, il
+PRIME sur l'intention de la commande.
+.TP
+.B APP_ENV
+Environnement de DÉPLOIEMENT, libre (staging, canary, prod\-eu). Axe distinct
+du mode d'exécution.
+.TP
+.B NF_*
+Toute variable lue par Nodefony porte ce préfixe. nodefony env en dresse la
+cascade et la provenance.
+.TP
+.B NF__<MODULE>__<CHEMIN>
+Surcharge une clé de configuration d'un module (double souligné entre les
+niveaux), appliquée avant la validation du schéma.
+.SH FILES
+.TP
+.B nodefony.config.ts
+Configuration de l'application. Sa présence marque la racine du projet.
+.TP
+.B env.ts
+Catalogue des variables d'environnement de l'application.
+.TP
+.B node_modules/.cache/nodefony/cli\-manifest.json
+Cache des commandes, réécrit à chaque commande. Sert la complétion et le
+menu, qui doivent répondre sans démarrer l'application.
+.SH EXAMPLES
+.TP
+.B nodefony create app mon\-app
+Crée une application.
+.TP
+.B nodefony dev
+Démarre en développement, avec redémarrage à chaud.
+.TP
+.B nodefony inspect routes
+Affiche les routes RÉELLEMENT montées, sans ouvrir de port.
+.TP
+.B nodefony doctor
+Diagnostique le projet, même s'il ne démarre plus.
+.SH SEE ALSO
+La documentation complète vit dans le projet (\fBdocs/\fR) et dans la console
+d'administration. \fBnodefony card\fR rend la carte de visite de l'application
+: où aller, quoi lancer.
+.SH AUTHOR
+Christophe CAMENSULI et les contributeurs de Nodefony.