odoro 1.0.9 → 2.1.0

package/templates/react-ts-server/client/src/router.tsx

@@ -1,72 +1,104 @@
 /**
- * Le routeur du projet.
+ * The router of the project.
  *
- * ## Pourquoi il vit seul, dans son fichier
+ * ## Why it lives alone, in its own file
  *
- * C'est le seul endroit qui nomme la dependance de routage. Changer de routeur,
- * ajouter une route, en proteger une derriere une authentification : tout se
- * lit ici, et `App.tsx` n'a rien a en savoir au-dela de la ligne qui l'importe.
+ * This is the only place that names the routing dependency. Switching routers,
+ * adding a route, putting one behind authentication: it all reads here, and
+ * `App.tsx` needs to know nothing beyond the line that imports it.
  *
- * ## Pourquoi les pages sont passees, et non importees
+ * ## Why the pages are passed in, and not imported
  *
- * Ce fichier pourrait importer les pages depuis `App.tsx`. Les deux modules
- * s'importeraient alors l'un l'autre : cela fonctionne, mais l'ordre
- * d'evaluation devient une question a laquelle personne ne veut repondre le
- * jour ou quelque chose s'execute au chargement du module.
+ * This file could import the pages from `App.tsx`. The two modules would then
+ * import each other: that works, but evaluation order becomes a question
+ * nobody wants to answer the day something runs at module load.
  *
- * Les pages arrivent donc en proprietes. La dependance ne va que dans un sens —
- * `App.tsx` connait le routeur, le routeur ne connait que React — et la table
- * des routes reste lisible d'un coup d'oeil.
+ * So the pages arrive as properties. The dependency only goes one way —
+ * `App.tsx` knows the router, the router only knows React — and the route
+ * table stays readable at a glance.
  *
  * @module
  */
 
-import { Outlet, Route, Router, Routes } from '@odoro-cli/libs/router'
+import {
+  Outlet,
+  Route,
+  // Aliased: the component exported below is the one the application sees, and
+  // it takes the name `Router`.
+  Router as RouterProvider,
+  Routes,
+  createMemoryHistory,
+} from '@odoro-cli/libs/router'
 import type { ReactElement, ReactNode } from 'react'
 
 export { Link, useLocation } from '@odoro-cli/libs/router'
 
-/** Les pages que le routeur place. */
-export interface RouteurProps {
-  /** L'enveloppe commune : navigation, contenu, pied de page. */
-  readonly enveloppe: (contenu: ReactNode) => ReactElement
-  /** La page d'accueil. */
-  readonly accueil: ReactElement
-  /** La page « A propos ». */
-  readonly apropos: ReactElement
-  /** Ce qui s'affiche quand aucune route ne correspond. */
-  readonly introuvable: ReactElement
+/** The pages the router places. */
+export interface RouterProps {
+  /** The common shell: navigation, content, footer. */
+  readonly shell: (content: ReactNode) => ReactElement
+  /** The home page. */
+  readonly home: ReactElement
+  /** The "About" page. */
+  readonly about: ReactElement
+  /** The sign-in form. */
+  readonly signIn: ReactElement
+  /** The registration form. */
+  readonly register: ReactElement
+  /** The profile of the signed-in account. */
+  readonly profile: ReactElement
+  /** What shows when no route matches. */
+  readonly notFound: ReactElement
+  /**
+   * The address to render, when there is no address bar.
+   *
+   * That is the case while prerendering: the page is made on the build
+   * machine, where `window` does not exist and nothing says which route is
+   * being asked for. The in-memory history takes over then.
+   *
+   * In the browser it stays absent and the router reads the real address.
+   */
+  readonly url?: string
 }
 
 /**
- * La table des routes.
+ * The route table.
  *
  * @example
- * <Routeur
- *   enveloppe={(contenu) => <Coquille>{contenu}</Coquille>}
- *   accueil={<Accueil />}
- *   apropos={<APropos />}
- *   introuvable={<Introuvable />}
+ * <Router
+ *   shell={(content) => <Shell>{content}</Shell>}
+ *   home={<Home />}
+ *   about={<About />}
+ *   notFound={<NotFound />}
  * />
  */
-export function Routeur({
-  enveloppe,
-  accueil,
-  apropos,
-  introuvable,
-}: RouteurProps): ReactElement {
+export function Router({
+  shell,
+  home,
+  about,
+  signIn,
+  register,
+  profile,
+  notFound,
+  url,
+}: RouterProps): ReactElement {
   return (
-    <Router>
+    <RouterProvider
+      history={url === undefined ? undefined : createMemoryHistory([url])}
+    >
       <Routes>
-        {/* `Outlet` marque l'endroit ou la page courante se rend : c'est ce
-            qui permet a la navigation et au pied de page de ne pas etre
-            remontes a chaque changement de route. */}
-        <Route path="/" element={enveloppe(<Outlet />)}>
-          <Route index element={accueil} />
-          <Route path="a-propos" element={apropos} />
-          <Route path="*" element={introuvable} />
+        {/* `Outlet` marks the place where the current page renders: that is
+            what keeps the navigation and the footer from being remounted on
+            every route change. */}
+        <Route path="/" element={shell(<Outlet />)}>
+          <Route index element={home} />
+          <Route path="about" element={about} />
+          <Route path="sign-in" element={signIn} />
+          <Route path="register" element={register} />
+          <Route path="profile" element={profile} />
+          <Route path="*" element={notFound} />
         </Route>
       </Routes>
-    </Router>
+    </RouterProvider>
   )
 }

package/templates/react-ts-server/client/src/styles.css

@@ -1,9 +1,9 @@
-/* Styles propres a l'application.
+/* Styles that belong to the application.
 
-   Tout le reste vient des jetons Odoro : surcharger une variable ci-dessous
-   retheme l'ensemble, composants de la librairie compris. La teinte de marque
-   est `--o-palette-brand-500` ; la remplacer suffit a changer la couleur de la
-   page, du signe et des boutons d'un seul coup. */
+   Everything else comes from the Odoro tokens: overriding a variable below
+   rethemes the whole thing, library components included. The brand hue is
+   `--o-palette-brand-500`; replacing it is enough to change the colour of the
+   page, of the mark and of the buttons in one go. */
 
 .app-shell {
   min-height: 100dvh;

package/templates/react-ts-server/odoro.config.ts

@@ -1,19 +1,22 @@
 import { defineConfig } from 'odoro'
 
 export default defineConfig({
-  // Le client vit dans son propre dossier : la racine du moteur l'y suit.
+  // The client lives in its own directory: the engine root follows it there.
   root: 'client',
   alias: {
     '@': 'src',
   },
   build: {
-    // Le serveur sert ce dossier en production.
+    // The server serves this directory in production.
     outDir: '../dist/client',
+    // Every route becomes a complete document. See
+    // `client/src/entry-server.tsx` for the list, and for how to do without it.
+    prerender: true,
   },
   server: {
     port: 5180,
-    // Les appels d'API sont transmis au serveur, qui tourne en parallele :
-    // le navigateur ne voit qu'une seule origine, donc aucune question de CORS.
+    // API calls are forwarded to the server, which runs alongside: the browser
+    // only ever sees one origin, so no CORS question arises.
     proxy: {
       '/api': 'http://localhost:3001',
     },

package/templates/react-ts-server/package.json

@@ -16,11 +16,13 @@
     "@odoro-cli/libs": "latest",
     "@odoro-cli/server": "latest",
     "express": "^5.1.0",
+    "pg": "^8.16.3",
     "react": "^19.2.0",
     "react-dom": "^19.2.0",
     "zod": "^4.5.1"
   },
   "devDependencies": {
+    "@types/pg": "^8.15.6",
     "@types/express": "^5.0.3",
     "@types/node": "^22.18.8",
     "@types/react": "^19.2.2",

package/templates/react-ts-server/scripts/dev.mjs

@@ -1,21 +1,21 @@
 /**
- * Lance le client et le serveur en parallele.
+ * Runs the client and the server side by side.
  *
- * Un script maison plutot qu'une dependance : le besoin tient en cinquante
- * lignes, et il vaut mieux que la sortie des deux processus reste lisible et
- * qu'une interruption les arrete tous les deux proprement.
+ * A home-made script rather than a dependency: the need fits in fifty lines,
+ * and it is better that the output of both processes stays readable and that
+ * an interrupt stops both of them cleanly.
  */
 
 import { spawn } from 'node:child_process'
 
-const RESET = '\u001b[0m'
+const RESET = ''
 
-/** Processus a lancer, avec leur etiquette et leur couleur. */
+/** Processes to start, with their label and their colour. */
 const TASKS = [
-  { label: 'client', color: '\u001b[35m', command: 'odoro', args: ['dev'] },
+  { label: 'client', color: '', command: 'odoro', args: ['dev'] },
   {
-    label: 'serveur',
-    color: '\u001b[36m',
+    label: 'server',
+    color: '',
     command: 'tsx',
     args: ['watch', 'server/src/main.ts'],
   },
@@ -23,7 +23,7 @@ const TASKS = [
 
 const children = []
 
-/** Prefixe chaque ligne de sortie par l'etiquette de son processus. */
+/** Prefixes every output line with the label of its process. */
 function pipe(stream, label, color) {
   let buffer = ''
   stream.setEncoding('utf8')
@@ -37,7 +37,7 @@ function pipe(stream, label, color) {
   })
 }
 
-/** Arrete tous les processus encore vivants. */
+/** Stops every process still alive. */
 function stopAll() {
   for (const child of children) {
     if (child.exitCode === null && !child.killed) child.kill()
@@ -47,7 +47,7 @@ function stopAll() {
 for (const task of TASKS) {
   const child = spawn(task.command, task.args, {
     stdio: ['inherit', 'pipe', 'pipe'],
-    // Sous Windows, les binaires de node_modules sont des scripts shell.
+    // On Windows, the binaries in node_modules are shell scripts.
     shell: process.platform === 'win32',
   })
 
@@ -55,9 +55,9 @@ for (const task of TASKS) {
   pipe(child.stderr, task.label, task.color)
 
   child.on('exit', (code) => {
-    // Si l'un s'arrete, l'autre n'a plus de raison de tourner.
+    // If one stops, the other has no reason left to run.
     if (code !== 0 && code !== null) {
-      process.stderr.write(`[${task.label}] arret avec le code ${code}\n`)
+      process.stderr.write(`[${task.label}] stopped with code ${code}\n`)
     }
     stopAll()
     process.exitCode = code ?? 0

package/templates/react-ts-server/server/src/main.ts

@@ -1,22 +1,21 @@
 /**
- * Le serveur applicatif : un assemblage de modules, rien de plus.
+ * The application server: an assembly of modules, nothing more.
  *
- * ## Ce fichier ne contient aucune logique
+ * ## This file holds no logic
  *
- * C'est voulu. Tout ce qu'une application fait vit dans un module, et ce
- * fichier ne fait que dire lesquels sont actifs. Activer ou desactiver une
- * fonctionnalite tient alors en une ligne, et rien d'autre ne bouge.
+ * That is deliberate. Everything an application does lives in a module, and
+ * this file does nothing but say which ones are active. Enabling or disabling
+ * a feature then takes one line, and nothing else moves.
  *
- * Un serveur ou les routes s'ajoutent directement ici finit par melanger
- * l'assemblage et le metier, et « desactiver l'authentification » devient un
- * travail d'archeologie plutot qu'une ligne commentee.
+ * A server where routes are added directly here ends up mixing the assembly
+ * with the domain, and "disable authentication" becomes a piece of archaeology
+ * rather than a commented line.
  *
- * ## En developpement et en production
+ * ## In development and in production
  *
- * En developpement, ce serveur n'expose que l'API : le client est servi par
- * Odoro, qui lui transmet les appels commencant par `/api`. En production, il
- * sert en plus le resultat de la compilation du client — une seule chose a
- * deployer.
+ * In development, this server exposes only the API: the client is served by
+ * Odoro, which forwards the calls starting with `/api` to it. In production,
+ * it also serves the result of the client build — a single thing to deploy.
  *
  * @module
  */
@@ -34,12 +33,20 @@ import {
 } from '@odoro-cli/server'
 import express from 'express'
 
+import { createAuthModule } from './modules/auth/index.js'
 import { createHealthModule } from './modules/health/index.js'
 
-/** Racine du module compile, pour retrouver le client a cote. */
+/** Root of the compiled module, to find the client next to it. */
 const HERE = dirname(fileURLToPath(import.meta.url))
 
-/** Assemble l'application. Exporte pour que les tests la montent sans l'ecouter. */
+/**
+ * Assembles the application. Exported so that tests can mount it without
+ * listening.
+ *
+ * @returns `app` is the kernel and its modules; `express` is what has to be
+ *   listened on — in production, a wrapper that serves the built client first.
+ *   An API test mounts `app.express`; an end-to-end test, `express`.
+ */
 export function buildServer() {
   const config = loadConfig()
 
@@ -48,20 +55,26 @@ export function buildServer() {
     pretty: config.NODE_ENV === 'development',
   })
 
-  // La configuration et le journal sont dans le conteneur : un module les y
-  // trouve sans qu'on les lui passe de main en main a travers trois couches.
+  // The configuration and the logger are in the container: a module finds them
+  // there without their being handed down through three layers.
   const container = createContainer()
     .register('config', () => config)
     .register('logger', () => logger)
 
+  // The store comes back out: the guard reads it on every request, and the
+  // shutdown has to close its connections.
+  const auth = createAuthModule(config)
+
   const app = createApp({
     config,
     logger,
     container: container as never,
+    authenticate: auth.authenticate,
     modules: [
       createHealthModule(config),
-      // Les modules du socle s'ajoutent ici, dans n'importe quel ordre :
-      // le noyau les trie selon leurs dependances.
+      auth.module,
+      // The foundation modules are added here, in any order: the kernel sorts
+      // them according to their dependencies.
       //
       //   authModule,
       //   accountModule,
@@ -69,58 +82,119 @@ export function buildServer() {
     ],
   })
 
-  if (config.NODE_ENV === 'production') {
-    // `dist/server/main.js` -> `dist/client`
-    const client = resolve(HERE, '..', 'client')
-    if (existsSync(client)) {
-      app.express.use(
-        express.static(client, { index: false, maxAge: '1y', immutable: true }),
-      )
-      // Repli d'application monopage : toute route hors API rend le document,
-      // et c'est le routeur client qui decide de la suite.
-      app.express.get(/^(?!\/api\/).*/, (_request, response) => {
-        response.sendFile(join(client, 'index.html'))
-      })
+  // `dist/server/main.js` -> `dist/client`
+  const client = resolve(HERE, '..', 'client')
+  const servesTheClient = config.NODE_ENV === 'production' && existsSync(client)
+
+  if (!servesTheClient) return { app, express: app.express, config, logger, auth }
+
+  // ## Why one application wrapping another
+  //
+  // `createApp` ends by installing the 404 handler and the error handler.
+  // Anything mounted **after** it would therefore be unreachable: the request
+  // would already have its answer. The client was thus never served in
+  // production — with no error at startup, since the mounting succeeds; every
+  // page simply came back 404.
+  //
+  // So the wrapper handles the files first and only hands over to the API for
+  // what it has not served. The order is explicit, and the kernel stays free to
+  // end with its handlers.
+  const wrapper = express()
+  wrapper.set('trust proxy', true)
+  wrapper.disable('x-powered-by')
+
+  // `index: false`: without it, a directory would return its `index.html` with
+  // the cache header of a hashed file — one year, immutable —, and a wording
+  // fix would stay invisible for a year. Those documents go through the
+  // handling below, with no caching.
+  //
+  // `redirect: false`: prerendering drops one directory per route, and without
+  // it `/about` answered with a redirect to `/about/`. One more round trip,
+  // and above all an address that is not the one that was published.
+  wrapper.use(
+    express.static(client, {
+      index: false,
+      redirect: false,
+      maxAge: '1y',
+      immutable: true,
+    }),
+  )
+
+  // A prerendered route is served as it stands; everything else falls back to
+  // the document, and the client router decides what happens next.
+  //
+  // Without this lookup, `/about` would receive the document of the root: the
+  // page would end up showing, once the script had run, but the prerendered
+  // HTML — the one robots and link previews read — would be the home page's,
+  // with its title and its description.
+  wrapper.get(/^(?!\/api\/).*/, (request, response, next) => {
+    const route = request.path.replace(/^\/+|\/+$/g, '')
+    const prerendered = route === '' ? undefined : resolve(client, route, 'index.html')
+
+    if (
+      prerendered !== undefined &&
+      prerendered.startsWith(client) &&
+      existsSync(prerendered)
+    ) {
+      response.sendFile(prerendered)
+      return
     }
-  }
 
-  return { app, config, logger }
+    const document = join(client, 'index.html')
+    if (!existsSync(document)) {
+      // The client has not been built: the API will answer, and its 404 will
+      // at least say that no route matches.
+      next()
+      return
+    }
+    response.sendFile(document)
+  })
+
+  wrapper.use(app.express)
+
+  return { app, express: wrapper, config, logger, auth }
 }
 
-/** Demarre le serveur. */
+/** Starts the server. */
 function main(): void {
   let server
   try {
     server = buildServer()
   } catch (cause) {
     if (cause instanceof ConfigError) {
-      // La configuration est incomplete : le message liste tout ce qui manque,
-      // d'un coup. Rien ne sert de demarrer a moitie.
+      // The configuration is incomplete: the message lists everything that is
+      // missing, at once. There is no point starting halfway.
       console.error(cause.message)
       process.exit(1)
     }
     throw cause
   }
 
-  const { app, config, logger } = server
+  // `express` and not `app.express`: it is the wrapper that serves the client
+  // before handing over to the API. In development the two are the same thing.
+  const { express: application, config, logger, auth } = server
 
-  const listener = app.express.listen(config.PORT, () => {
-    logger.info({ port: config.PORT, environment: config.NODE_ENV }, 'serveur a l ecoute')
+  const listener = application.listen(config.PORT, () => {
+    logger.info({ port: config.PORT, environment: config.NODE_ENV }, 'server listening')
   })
 
-  // Arret propre : on cesse d'accepter, on laisse finir ce qui est en cours, et
-  // on abandonne au-dela du delai plutot que de rester suspendu.
+  // Graceful shutdown: stop accepting, let what is in flight finish, and give
+  // up past the deadline rather than hanging.
   const stop = (signal: string): void => {
-    logger.info({ signal }, 'arret demande')
+    logger.info({ signal }, 'shutdown requested')
     const deadline = setTimeout(() => {
-      logger.warn('delai depasse, arret force')
+      logger.warn('deadline exceeded, forcing shutdown')
       process.exit(1)
     }, config.SHUTDOWN_TIMEOUT)
     deadline.unref()
 
     listener.close(() => {
-      clearTimeout(deadline)
-      process.exit(0)
+      // The database connections go with the server. Left open, a hosted
+      // database counts them against the limit long after the process is gone.
+      void auth.store.dispose().finally(() => {
+        clearTimeout(deadline)
+        process.exit(0)
+      })
     })
   }