@nodefony/frontend 10.0.0-beta.2 → 10.0.0-beta.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (25) hide show
  1. package/README.md +38 -50
  2. package/dist/_virtual/{_@oxc-project_runtime@0.152.0 → _@oxc-project_runtime@0.153.0}/helpers/esm/decorate.js +1 -1
  3. package/dist/_virtual/{_@oxc-project_runtime@0.152.0 → _@oxc-project_runtime@0.153.0}/helpers/esm/decorateMetadata.js +1 -1
  4. package/dist/index.js +2 -2
  5. package/dist/nodefony/config/config.js +3 -8
  6. package/dist/nodefony/service/FrontendService.js +73 -295
  7. package/dist/nodefony/service/ViteConfigGenerator.js +11 -30
  8. package/dist/nodefony/service/ViteProcessSupervisor.js +17 -12
  9. package/dist/nodefony/service/bootSummary.js +44 -0
  10. package/dist/nodefony/src/isolationGroups.js +27 -32
  11. package/dist/nodefony/src/template/TemplateHelper.js +52 -19
  12. package/dist/types/nodefony/config/config.d.ts +0 -8
  13. package/dist/types/nodefony/interfaces/IFrontBuilder.d.ts +0 -9
  14. package/dist/types/nodefony/interfaces/IFrontendService.d.ts +6 -10
  15. package/dist/types/nodefony/interfaces/IViteSupervisor.d.ts +11 -5
  16. package/dist/types/nodefony/service/FrontendService.d.ts +24 -118
  17. package/dist/types/nodefony/service/ViteConfigGenerator.d.ts +13 -21
  18. package/dist/types/nodefony/service/ViteProcessSupervisor.d.ts +13 -16
  19. package/dist/types/nodefony/service/bootSummary.d.ts +23 -0
  20. package/dist/types/nodefony/src/isolationGroups.d.ts +24 -23
  21. package/dist/types/nodefony/src/template/TemplateHelper.d.ts +23 -7
  22. package/docs/index.md +173 -145
  23. package/package.json +12 -12
  24. package/dist/nodefony/src/remoteDev.js +0 -216
  25. package/dist/types/nodefony/src/remoteDev.d.ts +0 -152
package/README.md CHANGED
@@ -12,7 +12,7 @@ Vite a besoin d'un event-loop et d'un tas V8 pour compiler/HMR. L'exécuter **in
12
12
 
13
13
  - Crash Vite ≠ crash Nodefony
14
14
  - Compilation Vite ≠ latence event-loop Nodefony
15
- - HMR WebSocket de Vite reste autonome
15
+ - HMR WebSocket de Vite relayé par Nodefony, sur l'origine de la page
16
16
  - Auto-restart en cas de mort du child (résilience built-in)
17
17
 
18
18
  ---
@@ -68,9 +68,6 @@ class MyModule extends Module {
68
68
  root: "./frontend", // contient index.html
69
69
  outDir: "./public/dist", // pour la prod build
70
70
  name: "my-module", // nom logique (entryName)
71
- // Quand le browser fait fetch("/my/api/x") depuis l'app Vite,
72
- // Vite proxifie vers Nodefony :
73
- apiProxyPaths: ["/my/api"],
74
71
  });
75
72
  return this;
76
73
  }
@@ -126,18 +123,13 @@ class MyController extends Controller {
126
123
  // origines Vite au firewall (`@nodefony/security`), qui émet UN seul
127
124
  // en-tête. Un controller qui le réécrirait écraserait le nonce.
128
125
 
129
- // Deux données de la requête sont propagées au rendu :
130
- // - le nonce CSP, sans lequel `script-src 'nonce-…'` bloque les balises ;
131
- // - l'hôte, dont l'origine des assets Vite est dérivée en développement —
132
- // la page annonce l'origine par laquelle le client est arrivé, si bien
133
- // qu'un poste et un navigateur en conteneur sont servis en même temps,
134
- // sans configuration. Scheme et port restent ceux de Vite.
126
+ // Le nonce CSP de la requête est propagé au rendu : sans lui,
127
+ // `script-src 'nonce-…'` bloque les balises. En développement, les URLs
128
+ // vers Vite sont relatives à la page (`/_vite/<famille>/…`) : un poste et
129
+ // un navigateur en conteneur sont servis en même temps, sans configuration.
135
130
  const viteTags =
136
- svc?.renderTags(
137
- "my-module",
138
- this.context?.cspNonce,
139
- this.context?.domain,
140
- ) ?? "<!-- @nodefony/frontend not started -->";
131
+ svc?.renderTags("my-module", this.context?.cspNonce) ??
132
+ "<!-- @nodefony/frontend not started -->";
141
133
 
142
134
  return this.render(`<!DOCTYPE html>
143
135
  <html lang="en">
@@ -167,7 +159,9 @@ INFO frontend : registered entry: my-module (react19) from "my-module"
167
159
  INFO frontend : vite [default] ready on 127.0.0.1:5173
168
160
  ```
169
161
 
170
- Va sur `http://127.0.0.1:5151/my-route/` — Nodefony rend l'HTML, le browser tape Vite (5173) pour les assets, HMR fonctionne en édition de `App.tsx`.
162
+ Va sur `https://127.0.0.1:5152/my-route/` — Nodefony rend l'HTML, et relaie à Vite tout ce qui passe sous `/_vite/<famille>/` (modules, styles, socket du rechargement à chaud). Le navigateur ne voit qu'**une** origine : un seul certificat, pas de contenu mixte. HMR fonctionne en édition de `App.tsx`.
163
+
164
+ Pour ouvrir la page depuis un téléphone du réseau local : `NF_BIND_ALL=true` (application générée), puis `https://<IP-de-ta-machine>:5152/my-route/` — détail dans la [documentation du module](docs/index.md#-hors-de-la-boucle-locale--téléphone-conteneur-réseau).
171
165
 
172
166
  ---
173
167
 
@@ -178,19 +172,11 @@ Dans le `config.ts` de **ton app** ou de **ton module** :
178
172
  ```ts
179
173
  const config = {
180
174
  "module-frontend": {
181
- devHost: "127.0.0.1", // host d'écoute Vite
182
- devPort: 5173, // port Vite (incrémenté si occupé)
175
+ devHost: "127.0.0.1", // écoute de Vite — boucle locale, Nodefony le relaie
176
+ devPort: 5173, // port Vite interne (incrémenté si occupé)
183
177
  autoStartInDevelopment: true, // démarre Vite en env=development
184
178
  pipeViteLogs: true, // logs Vite dans syslog Nodefony
185
179
 
186
- // HTTPS — partage les certs Nodefony (server-https 5152)
187
- https: true, // false par défaut
188
-
189
- // Proxy backend Vite → Nodefony
190
- backendHost: "127.0.0.1",
191
- backendPort: 5151,
192
- backendProtocol: "http", // http | https
193
-
194
180
  // Variables d'env passées à Vite (les VITE_* sont exposées au browser)
195
181
  viteEnv: {
196
182
  VITE_API_BASE: "/api/v1",
@@ -218,12 +204,12 @@ Tout est optionnel — les defaults fonctionnent out-of-the-box.
218
204
 
219
205
  `FrontendService` est un `Service` Nodefony (donc un `EventEmitter`). Tu peux écouter :
220
206
 
221
- | Event | Payload | Quand |
222
- | ------------------- | ---------------------------- | --------------------------------------- |
223
- | `frontend:starting` | `{ backendOrigin, entries }` | Juste avant le spawn Vite |
224
- | `frontend:ready` | `IViteSupervisorStatus` | Vite a annoncé `Local:` dans son stdout |
225
- | `frontend:error` | `Error` | Spawn ou ready timeout échoué |
226
- | `frontend:stopped` | (rien) | Après `stop()` propre (SIGINT envoyé) |
207
+ | Event | Payload | Quand |
208
+ | ------------------- | ----------------------- | --------------------------------------- |
209
+ | `frontend:starting` | `{ entries }` | Juste avant le spawn Vite |
210
+ | `frontend:ready` | `IViteSupervisorStatus` | Vite a annoncé `Local:` dans son stdout |
211
+ | `frontend:error` | `Error` | Spawn ou ready timeout échoué |
212
+ | `frontend:stopped` | (rien) | Après `stop()` propre (SIGINT envoyé) |
227
213
 
228
214
  Exemple :
229
215
 
@@ -247,10 +233,10 @@ interface IFrontendService {
247
233
  stopDev(): Promise<void>;
248
234
  // vite.build() par entrée ; bilan construits / ignorés / en échec
249
235
  build(opts?: { force?: boolean }): Promise<IFrontendBuildResult>;
250
- // `nonce` = `Context.cspNonce` ; `requestHost` = `Context.domain` (sans port),
251
- // dont l'origine des assets est dérivée en développement.
252
- renderTags(entryName, nonce?, requestHost?): string;
253
- renderDocument(entryName, nonce?, requestHost?): string;
236
+ // `nonce` = `Context.cspNonce` ; en développement, les URLs vers Vite sont
237
+ // relatives à la page (`/_vite/<famille>/…`).
238
+ renderTags(entryName, nonce?): string;
239
+ renderDocument(entryName, nonce?): string;
254
240
  assetUrl(path): string;
255
241
  }
256
242
  ```
@@ -263,18 +249,15 @@ interface IFrontendService {
263
249
 
264
250
  ### Page blanche, scripts bloqués par CSP
265
251
 
266
- En développement, le service déclare les origines Vite au pare-feu (`@nodefony/security`) une fois
267
- Vite prêt, et ce dernier émet UN seul en-tête CSP avec le nonce de la requête. Vérifie que tu passes
252
+ En développement, le service déclare son fragment CSP au pare-feu (`@nodefony/security`) une fois
253
+ Vite prêt — sans aucune origine, tout passe par celle de la page — et ce dernier émet UN seul
254
+ en-tête CSP avec le nonce de la requête. Vérifie que tu passes
268
255
  `this.context?.cspNonce` à `svc.renderTags(…)` / `renderDocument(…)`, et ne réécris jamais l'en-tête
269
256
  dans le contrôleur : tu écraserais le nonce.
270
257
 
271
258
  ### `Unexpected token '<'` sur `fetch("/api/...")`
272
259
 
273
- Vite sert son SPA-fallback HTML pour les routes inconnues. Déclare le préfixe dans `apiProxyPaths` :
274
-
275
- ```ts
276
- svc.registerEntry(this, { ..., apiProxyPaths: ["/my/api"] });
277
- ```
260
+ La page est ouverte sur le port de Vite, qui sert son SPA-fallback HTML pour les routes inconnues. Ouvre-la par Nodefony : le `fetch` part alors vers lui, sur l'origine de la page. Il n'y a pas de proxy d'API à déclarer — `apiProxyPaths` et les options `backendHost`/`backendPort`/`backendProtocol` ont été retirés.
278
261
 
279
262
  ### `@vitejs/plugin-react can't detect preamble`
280
263
 
@@ -284,9 +267,13 @@ Le `TemplateHelper` injecte automatiquement le preamble React Fast Refresh pour
284
267
 
285
268
  Le port configuré est pris. Le supervisor retry automatiquement sur `port+1`, `port+2` (option `portRetryAttempts`). Vérifie le port résolu via `svc.status().port` — il vaut `null` tant qu'aucun port n'a été résolu, jamais le port demandé : un port qu'on espère n'est pas un port qui sert.
286
269
 
287
- ### Le browser refuse le cert HTTPS de Vite (`https: true`)
270
+ ### Le navigateur alerte sur le certificat de développement
271
+
272
+ Accepte-le **une** fois sur la page : modules et socket passent par la même origine, donc par le même certificat. Ou installe la CA root Nodefony : `nodefony/config/certificates/ca/nodefony-root-ca.crt.pem` dans ton trousseau.
273
+
274
+ ### Connexion refusée depuis un téléphone
288
275
 
289
- Va sur `https://127.0.0.1:5173/` une fois et accepte le certificat. Ou installe la CA root Nodefony : `nodefony/config/certificates/ca/nodefony-root-ca.crt.pem` dans ton trousseau.
276
+ En développement, l'application n'écoute que la boucle locale. `NF_BIND_ALL=true` l'ouvre au réseau local (application générée) — à réserver à un réseau de confiance.
290
277
 
291
278
  ### Vite crash en boucle (`max restarts reached`)
292
279
 
@@ -318,7 +305,8 @@ Kernel "onServersReady" ← 4 servers Nodefony écoutent
318
305
  FrontendService.startDev()
319
306
  ↓
320
307
  ViteProcessSupervisor.start()
321
- ├─ écrit vite.config.generated.mjs (proxy, https, base, env)
308
+ ├─ écrit vite.config.generated.mjs (base /_vite/<famille>/, env)
309
+ ├─ monte /_vite/<famille>/ sur le proxy inverse de @nodefony/http
322
310
  ├─ spawn(node, [vite.js, "--config", ...]) (repli npx si le binaire n'est pas résolu)
323
311
  ├─ parse stdout "Local: https://host:port" → state = "ready"
324
312
  ├─ attach exit handler (auto-restart si crash inattendu)
@@ -328,11 +316,11 @@ Browser GET /my-route/
328
316
  │
329
317
  Nodefony rend HTML + svc.renderTags() injecte:
330
318
  <script type="module"> preamble React Fast Refresh
331
- <script src="https://host:5173/@vite/client">
332
- <script src="https://host:5173/src/main.tsx">
319
+ <script src="/_vite/default/@vite/client">
320
+ <script src="/_vite/default/@fs/…/src/main.tsx">
333
321
 
334
- Browser → 5173 (Vite) pour les assets + HMR WSS
335
- Browser → 5173 pour /api/... → Vite proxifie vers Nodefony (5151/5152)
322
+ Browser → Nodefony (5152) /_vite/… → relais → Vite 127.0.0.1:5173 (assets + HMR WSS)
323
+ Browser → Nodefony (5152) /api/… → ton contrôleur, sans proxy
336
324
  ```
337
325
 
338
326
  Détails internes (dans le dépôt) : voir [`CLAUDE.md`](https://github.com/nodefony/nodefony-core/blob/main/src/packages/@nodefony/frontend/CLAUDE.md) et [`MEMORY.md`](https://github.com/nodefony/nodefony-core/blob/main/src/packages/@nodefony/frontend/MEMORY.md).
@@ -1,4 +1,4 @@
1
- //#region \0@oxc-project+runtime@0.152.0/helpers/esm/decorate.js
1
+ //#region \0@oxc-project+runtime@0.153.0/helpers/esm/decorate.js
2
2
  function __decorate(decorators, target, key, desc) {
3
3
  var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
4
4
  if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
@@ -1,4 +1,4 @@
1
- //#region \0@oxc-project+runtime@0.152.0/helpers/esm/decorateMetadata.js
1
+ //#region \0@oxc-project+runtime@0.153.0/helpers/esm/decorateMetadata.js
2
2
  function __decorateMetadata(k, v) {
3
3
  if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
4
4
  }
package/dist/index.js CHANGED
@@ -10,8 +10,8 @@ import { ViteBuilder } from "./nodefony/src/builders/ViteBuilder.js";
10
10
  import { ViteConfigGenerator } from "./nodefony/service/ViteConfigGenerator.js";
11
11
  import { ViteProcessSupervisor } from "./nodefony/service/ViteProcessSupervisor.js";
12
12
  import { TemplateHelper } from "./nodefony/src/template/TemplateHelper.js";
13
- import __decorateMetadata from "./_virtual/_@oxc-project_runtime@0.152.0/helpers/esm/decorateMetadata.js";
14
- import __decorate from "./_virtual/_@oxc-project_runtime@0.152.0/helpers/esm/decorate.js";
13
+ import __decorateMetadata from "./_virtual/_@oxc-project_runtime@0.153.0/helpers/esm/decorateMetadata.js";
14
+ import __decorate from "./_virtual/_@oxc-project_runtime@0.153.0/helpers/esm/decorate.js";
15
15
  import FrontendService_default from "./nodefony/service/FrontendService.js";
16
16
  import { buildFrontendStatus, createFrontendAdminApi } from "./nodefony/src/FrontendAdminApi.js";
17
17
  import FrontendBuild from "./nodefony/command/frontend-build.js";
@@ -40,20 +40,15 @@ const resilienceSchema = z.strictObject({
40
40
  portRetryAttempts: z.number().int().positive().default(3).describe("Nombre de ports à essayer sur `EADDRINUSE` (devPort, devPort+1, …). Défaut : 3.")
41
41
  }).describe("Résilience du superviseur Vite (auto-restart, backoff, health check). Toutes optionnelles — les défauts internes s'appliquent si rien n'est fourni.");
42
42
  const frontendConfigSchema = z.strictObject({
43
- devHost: z.string().default("127.0.0.1").describe("Host d'écoute du dev server Vite — utilisé tel quel dans les `<script>` injectés (doit être joignable depuis le navigateur). Prod : N/A (Vite ne tourne pas en prod, le manifest pilote)."),
44
- devPort: z.number().int().positive().default(5173).describe("Port d'écoute du dev server Vite (5173 par défaut) — port de BASE : chaque famille de frontends prend le bloc suivant. Si occupé, c'est le SUPERVISEUR qui relance sur le port suivant (`resilience.portRetryAttempts` essais) et publie le port réel dans son `status()` — Vite, lui, ne se décale jamais seul : le fichier généré porte `strictPort` pour que l'origine annoncée au navigateur soit toujours celle qui sert."),
45
- publicOrigin: z.string().default("").refine((v) => v === "" || /^https?:\/\/[^/\s]+$/.test(v), { message: "publicOrigin doit être une origine (`scheme://host[:port]`), sans chemin" }).describe("Origine PUBLIQUE du dev server Vite — celle que le NAVIGATEUR utilise, quand elle diffère de l'adresse d'écoute (`devHost`). ÉPINGLE le rendu sur une origine unique : à réserver aux cas où un frontal la réécrit (tunnel, proxy, port remappé). Utilisée telle quelle (port inclus SEULEMENT si écrit) dans les `<script>` injectés, le `base` Vite et le WebSocket HMR (`hmr.host`/`clientPort`, dérivés). Vide (défaut, RECOMMANDÉ) = chaque page annonce l'origine par laquelle le client est arrivé (`Host` de la requête, scheme et port de Vite) : un poste et un navigateur en conteneur sont servis EN MÊME TEMPS par la même instance, sans configuration. Codespaces/Gitpod sont détectés automatiquement et fournissent alors l'origine par défaut — MAIS un client arrivé par la boucle locale (tunnel de port : VS Code Desktop le fait par défaut) reste servi en local, parce que l'origine publique d'une plateforme exige sa session, qu'une intégration continue ou une sonde n'a pas. Une origine écrite ICI, en revanche, gagne sur tout — c'est un réglage, pas une déduction. L'hôte d'une origine épinglée est automatiquement autorisé par Vite (`server.allowedHosts`) ; les hôtes suivis par la dérivation sont ceux de `trustedHosts` de @nodefony/http (une seule liste à maintenir : elle ouvre la barrière 421, Vite, le CSP et le rendu)."),
43
+ devHost: z.string().default("127.0.0.1").describe("Adresse d'écoute du dev server Vite. Défaut (RECOMMANDÉ) : la boucle locale — le navigateur ne joint jamais Vite directement, Nodefony le relaie sur l'origine de la page (`/_vite/<famille>/`). Prod : N/A (Vite ne tourne pas en prod, le manifest pilote)."),
44
+ devPort: z.number().int().positive().default(5173).describe("Port d'écoute du dev server Vite (5173 par défaut) — port de BASE : chaque famille de frontends prend le bloc suivant. Si occupé, c'est le SUPERVISEUR qui relance sur le port suivant (`resilience.portRetryAttempts` essais) et publie le port réel dans son `status()` — Vite, lui, ne se décale jamais seul : le fichier généré porte `strictPort` pour que le relais `/_vite/<famille>/` vise toujours le Vite qui sert. Le navigateur ne voit jamais ce port : il passe par l'origine de la page."),
46
45
  autoStartInDevelopment: z.boolean().default(true).describe("Démarre automatiquement le superviseur Vite quand le kernel passe en `development`. Ignoré en `production`/`staging`. Reco : true en dev, sinon les helpers template injecteront une URL morte."),
47
46
  defaultOutDir: z.string().default("./public/dist").describe("Dossier de sortie par défaut pour le build prod, relatif à la racine du module consommateur. Réécrit par la prop `outDir` de la déclaration d'entrée."),
48
47
  defaultRoot: z.string().default("./frontend").describe("Racine front par défaut (contient `index.html`) côté module."),
49
48
  assetBaseUrl: z.string().default("").describe("Base URL des assets servis en PRODUCTION (CDN / object storage / edge). Vide = assets servis depuis l'origine Nodefony en chemins relatifs (comportement historique). Renseignée (ex. `https://cdn.example.com`), elle préfixe le `base` Vite au build, les URLs de `renderProdTags` et le helper `asset('/x')`. N'affecte JAMAIS le mount `Statics`. Reco prod cloud-native : pointer le CDN devant l'object storage."),
50
49
  startupTimeoutMs: z.number().int().positive().default(3e4).describe("Timeout (ms) d'attente du `Local: http://…` dans le stdout Vite avant de considérer le démarrage comme cassé. Dev : 30s suffisent pour un cold-start Vite. Prod : N/A."),
51
50
  pipeViteLogs: z.boolean().default(true).describe("Propage les logs Vite vers le syslog Nodefony (sinon ils restent dans le stdout du process enfant uniquement)."),
52
- backendHost: z.string().default("127.0.0.1").describe("Host du serveur Nodefony cible du proxy Vite (`server.proxy`). Quand le navigateur fait `fetch(\"/api/...\")` depuis la page servie par Vite, Vite proxifie vers `${backendProtocol}://${backendHost}:${backendPort}`."),
53
- backendPort: z.number().int().positive().default(5151).describe("Port du serveur Nodefony cible du proxy Vite. HTTP par défaut (5151, config par défaut de `@nodefony/http`). Ajuster si l'app surcharge."),
54
- backendProtocol: z.enum(["http", "https"]).default("http").describe("Protocole du proxy Vite vers Nodefony. `http` par défaut — `https` pour proxifier vers le serveur HTTPS Nodefony (5152). Avec `https` et un certificat self-signed, prévoir `secure: false` côté proxy."),
55
- https: z.boolean().default(false).describe("Active HTTPS pour le dev server Vite (récupère les certificats du service `certificates` de `@nodefony/http`, mêmes certs que `server-https` 5152). Reco : true quand la page Nodefony est servie en HTTPS (5152) — évite le warning mixed-content. Le navigateur demandera la confiance pour 5173 si la CA root Nodefony n'est pas installée localement."),
56
- viteEnv: z.record(z.string(), z.string()).default({}).describe("Variables d'environnement supplémentaires passées au child Vite. Les clés préfixées `VITE_` sont exposées au navigateur via `import.meta.env.VITE_*` (ex. `{ VITE_API_BASE: \"/api/v1\" }`). Reco prod : utiliser un `.env.production` dans le `root` Vite plutôt que cette option, pour ne pas leak de secrets dans le code Nodefony."),
51
+ viteEnv: z.record(z.string(), z.string()).default({}).describe("Variables d'environnement supplémentaires passées au child Vite. Les clés préfixées `VITE_` sont exposées au navigateur via `import.meta.env.VITE_*` (ex. `{ VITE_API_BASE: \"/api/v1\" }`). Reco prod : utiliser un `.env.production` dans le `root` Vite plutôt que cette option, pour ne pas leak de secrets dans le code Nodefony. Ce fichier-là est lu par Vite lui-même (variables `VITE_` publiques) — rien à voir avec le `.env` de l'application."),
57
52
  resilience: resilienceSchema.default(() => resilienceSchema.parse({}))
58
53
  }).describe("Configuration de @nodefony/frontend (dev server Vite + build prod).");
59
54
  /**