odoro 0.1.0

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

@@ -0,0 +1,21 @@
+import { defineConfig } from 'odoro'
+
+export default defineConfig({
+  // Le client vit dans son propre dossier : la racine du moteur l'y suit.
+  root: 'client',
+  alias: {
+    '@': 'src',
+  },
+  build: {
+    // Le serveur sert ce dossier en production.
+    outDir: '../dist/client',
+  },
+  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.
+    proxy: {
+      '/api': 'http://localhost:3001',
+    },
+  },
+})

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

@@ -0,0 +1,33 @@
+{
+  "name": "odoro-app",
+  "private": true,
+  "version": "0.0.0",
+  "type": "module",
+  "scripts": {
+    "dev": "node scripts/dev.mjs",
+    "dev:client": "odoro dev",
+    "dev:server": "tsx watch server/src/main.ts",
+    "build": "odoro build && tsc -p server/tsconfig.json",
+    "start": "node dist/server/main.js",
+    "preview": "odoro preview",
+    "typecheck": "tsc --noEmit && tsc --noEmit -p server/tsconfig.json"
+  },
+  "dependencies": {
+    "@odoro-cli/libs": "^0.0.0",
+    "@odoro-cli/server": "^0.0.0",
+    "express": "^5.1.0",
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0",
+    "zod": "^4.5.1"
+  },
+  "devDependencies": {
+    "@types/express": "^5.0.3",
+    "@types/node": "^22.18.8",
+    "@types/react": "^19.2.2",
+    "@types/react-dom": "^19.2.1",
+    "odoro": "^0.0.0",
+    "pino-pretty": "^13.0.0",
+    "tsx": "^4.20.6",
+    "typescript": "^5.9.3"
+  }
+}

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

@@ -0,0 +1,74 @@
+/**
+ * Lance le client et le serveur en parallele.
+ *
+ * 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.
+ */
+
+import { spawn } from 'node:child_process'
+
+const RESET = '\u001b[0m'
+
+/** Processus a lancer, avec leur etiquette et leur couleur. */
+const TASKS = [
+  { label: 'client', color: '\u001b[35m', command: 'odoro', args: ['dev'] },
+  {
+    label: 'serveur',
+    color: '\u001b[36m',
+    command: 'tsx',
+    args: ['watch', 'server/src/main.ts'],
+  },
+]
+
+const children = []
+
+/** Prefixe chaque ligne de sortie par l'etiquette de son processus. */
+function pipe(stream, label, color) {
+  let buffer = ''
+  stream.setEncoding('utf8')
+  stream.on('data', (chunk) => {
+    buffer += chunk
+    const lines = buffer.split('\n')
+    buffer = lines.pop() ?? ''
+    for (const line of lines) {
+      process.stdout.write(`${color}[${label}]${RESET} ${line}\n`)
+    }
+  })
+}
+
+/** Arrete tous les processus encore vivants. */
+function stopAll() {
+  for (const child of children) {
+    if (child.exitCode === null && !child.killed) child.kill()
+  }
+}
+
+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.
+    shell: process.platform === 'win32',
+  })
+
+  pipe(child.stdout, task.label, task.color)
+  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 (code !== 0 && code !== null) {
+      process.stderr.write(`[${task.label}] arret avec le code ${code}\n`)
+    }
+    stopAll()
+    process.exitCode = code ?? 0
+  })
+
+  children.push(child)
+}
+
+for (const signal of ['SIGINT', 'SIGTERM']) {
+  process.on(signal, () => {
+    stopAll()
+    process.exit(0)
+  })
+}

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

@@ -0,0 +1,131 @@
+/**
+ * Le serveur applicatif : un assemblage de modules, rien de plus.
+ *
+ * ## Ce fichier ne contient aucune logique
+ *
+ * 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.
+ *
+ * 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.
+ *
+ * ## En developpement et en 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.
+ *
+ * @module
+ */
+
+import { existsSync } from 'node:fs'
+import { dirname, join, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+import {
+  ConfigError,
+  createApp,
+  createContainer,
+  createLogger,
+  loadConfig,
+} from '@odoro-cli/server'
+import express from 'express'
+
+import { createHealthModule } from './modules/health/index.js'
+
+/** Racine du module compile, pour retrouver le client a cote. */
+const HERE = dirname(fileURLToPath(import.meta.url))
+
+/** Assemble l'application. Exporte pour que les tests la montent sans l'ecouter. */
+export function buildServer() {
+  const config = loadConfig()
+
+  const logger = createLogger({
+    level: config.LOG_LEVEL,
+    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.
+  const container = createContainer()
+    .register('config', () => config)
+    .register('logger', () => logger)
+
+  const app = createApp({
+    config,
+    logger,
+    container: container as never,
+    modules: [
+      createHealthModule(config),
+      // Les modules du socle s'ajoutent ici, dans n'importe quel ordre :
+      // le noyau les trie selon leurs dependances.
+      //
+      //   authModule,
+      //   accountModule,
+      //   settingsModule,
+    ],
+  })
+
+  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'))
+      })
+    }
+  }
+
+  return { app, config, logger }
+}
+
+/** Demarre le serveur. */
+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.
+      console.error(cause.message)
+      process.exit(1)
+    }
+    throw cause
+  }
+
+  const { app, config, logger } = server
+
+  const listener = app.express.listen(config.PORT, () => {
+    logger.info({ port: config.PORT, environment: config.NODE_ENV }, 'serveur a l ecoute')
+  })
+
+  // 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.
+  const stop = (signal: string): void => {
+    logger.info({ signal }, 'arret demande')
+    const deadline = setTimeout(() => {
+      logger.warn('delai depasse, arret force')
+      process.exit(1)
+    }, config.SHUTDOWN_TIMEOUT)
+    deadline.unref()
+
+    listener.close(() => {
+      clearTimeout(deadline)
+      process.exit(0)
+    })
+  }
+
+  process.on('SIGTERM', () => stop('SIGTERM'))
+  process.on('SIGINT', () => stop('SIGINT'))
+}
+
+main()

package/templates/react-ts-server/server/src/modules/health/index.ts

@@ -0,0 +1,144 @@
+/**
+ * Module de sante — et exemple de ce a quoi ressemble un module.
+ *
+ * C'est le seul module de ce template, et il est ecrit ici plutot que fourni
+ * par `@odoro-cli/server` pour une raison : ecrire un module est la premiere chose
+ * qu'on fait sur ce socle, et un exemple qu'on peut ouvrir vaut mieux qu'une
+ * page de documentation.
+ *
+ * ## Un module est une fonction de ce dont il a besoin
+ *
+ * Celui-ci recoit la configuration en parametre plutot que de lire
+ * `process.env`. C'est la regle du socle : l'environnement est valide une fois,
+ * au demarrage, et tout le reste consomme le resultat. Une lecture directe
+ * echappe a cette validation et se manifeste a la centieme requete.
+ *
+ * ## Deux points de controle, et pourquoi ils different
+ *
+ * `/api/health` repond que **le processus vit**. Il ne teste rien d'autre, et
+ * doit repondre meme quand tout le reste est casse : c'est ce qu'un
+ * orchestrateur interroge pour decider s'il faut redemarrer le conteneur. Le
+ * faire dependre de la base ferait redemarrer un serveur parfaitement sain
+ * chaque fois que la base hoquette — et un redemarrage ne repare pas une base.
+ *
+ * `/api/ready` repond que **le service peut travailler**, et rend 503 tant
+ * qu'il manque quelque chose : c'est ce qu'un repartiteur interroge pour
+ * decider s'il peut envoyer du trafic.
+ *
+ * Confondre les deux donne l'un des deux defauts : un service qui redemarre en
+ * boucle pendant un incident de base, ou un repartiteur qui envoie du trafic a
+ * un service incapable de repondre.
+ *
+ * ## Pourquoi `/ready` echoue au premier demarrage
+ *
+ * Un projet fraichement echafaude n'a pas encore de `DATABASE_URL`. Le client
+ * demarre, l'interface s'affiche, et `/api/ready` dit ce qui manque. On voit
+ * donc quelque chose des la premiere minute, et on sait exactement ce qu'il
+ * reste a faire.
+ *
+ * @module
+ */
+
+import {
+  ServiceUnavailableError,
+  defineModule,
+  route,
+  type KernelConfig,
+} from '@odoro-cli/server'
+import { z } from 'zod'
+
+/** Ce que rend le controle de vie. */
+const liveness = z.object({
+  status: z.literal('ok'),
+  environment: z.string(),
+  uptime: z.number(),
+})
+
+/** Ce que rend le controle de disponibilite, quand tout repond. */
+const readiness = z.object({
+  ready: z.literal(true),
+  dependencies: z.array(z.object({ name: z.string(), detail: z.string() })),
+})
+
+/** Une dependance et son etat. */
+interface Dependency {
+  readonly name: string
+  readonly ready: boolean
+  readonly detail: string
+}
+
+/**
+ * Etat des dependances.
+ *
+ * La base n'est pas encore interrogee — le socle n'a pas sa couche de
+ * persistance. Ce qui est verifie ici est sa **configuration**, ce qui suffit
+ * a distinguer un projet qui n'a jamais recu d'URL d'un projet configure.
+ * Quand la persistance arrivera, c'est cette fonction qui apprendra a ouvrir
+ * une connexion, et rien d'autre ne changera.
+ */
+function inspect(config: KernelConfig): readonly Dependency[] {
+  const url = config.DATABASE_URL.trim()
+  return [
+    {
+      name: 'database',
+      ready: url.length > 0,
+      detail:
+        url.length > 0
+          ? 'URL configuree'
+          : 'DATABASE_URL absente — voir .env.example, ou lancer `odoro db:create`',
+    },
+  ]
+}
+
+/**
+ * Construit le module.
+ *
+ * @example
+ * createApp({ modules: [createHealthModule(config)], … })
+ */
+export function createHealthModule(config: KernelConfig) {
+  return defineModule({
+    name: 'health',
+    routes: [
+      route({
+        name: 'health.live',
+        method: 'GET',
+        path: '/api/health',
+        auth: 'public',
+        summary: 'Le processus repond.',
+        output: liveness,
+        handler: () => ({
+          status: 'ok' as const,
+          environment: config.NODE_ENV,
+          uptime: Math.round(process.uptime()),
+        }),
+      }),
+
+      route({
+        name: 'health.ready',
+        method: 'GET',
+        path: '/api/ready',
+        auth: 'public',
+        summary: 'Les dependances repondent.',
+        output: readiness,
+        handler: () => {
+          const dependencies = inspect(config)
+          const manquantes = dependencies.filter((d) => !d.ready)
+
+          if (manquantes.length > 0) {
+            // 503 et non 500 : la demande etait valide, c'est le service qui
+            // ne peut pas encore y repondre.
+            throw new ServiceUnavailableError(
+              manquantes.map((d) => `${d.name} — ${d.detail}`).join(' ; '),
+            )
+          }
+
+          return {
+            ready: true as const,
+            dependencies: dependencies.map(({ name, detail }) => ({ name, detail })),
+          }
+        },
+      }),
+    ] as never,
+  })
+}

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

@@ -0,0 +1,23 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["ES2023"],
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "moduleDetection": "force",
+    "verbatimModuleSyntax": true,
+    "types": ["node"],
+
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noFallthroughCasesInSwitch": true,
+
+    "skipLibCheck": true,
+    "outDir": "../dist/server",
+    "rootDir": "./src",
+    "sourceMap": true
+  },
+  "include": ["src"]
+}

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

@@ -0,0 +1,27 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["ES2023", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "moduleDetection": "force",
+    "jsx": "react-jsx",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "verbatimModuleSyntax": true,
+    "noEmit": true,
+
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noFallthroughCasesInSwitch": true,
+
+    "skipLibCheck": true,
+    "baseUrl": ".",
+    "paths": {
+      "@/*": ["./client/src/*"]
+    }
+  },
+  "include": ["client/src", "odoro.config.ts"]
+}