odoro 1.0.9 → 2.1.0

package/README.md

@@ -26,6 +26,10 @@ package is what it installs.
 
 Run `odoro --help` for the full list, including the database commands.
 
+Useful flags: `--mode <name>` picks the `.env` files and fills
+`import.meta.env.MODE`; `--prerender` renders routes to HTML; `--open` opens the
+browser; `--strict-port` fails instead of sliding to the next free port.
+
 ## Configuration
 
 ```ts
@@ -35,9 +39,99 @@ import { defineConfig } from 'odoro'
 export default defineConfig({
   alias: { '@': 'src' },
   server: { port: 5180 },
+  build: { prerender: true },
 })
 ```
 
+## Environment variables
+
+`.env` files are read for the current mode, least specific first:
+
+```
+.env  →  .env.local  →  .env.<mode>  →  .env.<mode>.local
+```
+
+A variable already present in the process environment is **never** overwritten by
+a file, so whatever your host injects wins.
+
+Only variables prefixed `ODORO_` reach the browser, through `import.meta.env`.
+Everything else stays on the machine — it is readable by the CLI and by your
+backend, and never enters the published bundle.
+
+```sh
+# .env
+ODORO_API=https://api.example.dev   # shipped to the browser
+DATABASE_URL=postgres://…           # stays here
+```
+
+Values may be quoted, span several lines (a PEM key), and refer to one another
+with `$OTHER`. Single quotes disable both escapes and expansion, which is how you
+write a password containing a `$`.
+
+Pick the mode with `--mode`: `odoro build --mode staging` reads `.env.staging`
+and sets `import.meta.env.MODE`.
+
+## Pre-rendering
+
+An SPA ships an empty document. A visitor never notices; a search engine, a link
+preview and a screen reader do. `build.prerender` renders your routes to HTML at
+build time, and the client hydrates them instead of rebuilding.
+
+```tsx
+// src/entry-server.tsx
+import { renderToString } from 'react-dom/server'
+import { App } from '@/App'
+
+export const routes = ['/', '/pricing']
+
+export function render(url: string) {
+  return { html: renderToString(<App url={url} />), head: `<title>…</title>` }
+}
+```
+
+`/pricing` becomes `dist/pricing/index.html`, which any static host serves
+without configuration. Nothing runs in production — the output is still files.
+
+## Build output
+
+`dist/manifest.json` maps every entry to its fingerprinted file, its stylesheets
+and its chunks, so a backend that renders its own document knows what to point
+at. Shared chunks are declared as `modulepreload` in the document, which removes
+one round trip per level of import depth.
+
+Sizes are reported both raw and gzipped, because gzipped is what ships.
+
+## Import suffixes and patterns
+
+```ts
+import charter from './CHARTER.md?raw' // the file's text
+import logo from './logo.svg?url' // its public URL, nothing loaded
+import Worker from './work.ts?worker' // compiled separately, run off-thread
+
+const pages = import.meta.glob('./pages/*.tsx')
+const titles = import.meta.glob('./pages/*.tsx', { eager: true, import: 'title' })
+```
+
+Patterns are resolved at build time into ordinary static imports, so code
+splitting and tree shaking still apply.
+
+## Plugins
+
+Three hooks, plus an escape hatch to esbuild for everything else.
+
+```ts
+import { defineConfig, type OdoroPlugin } from 'odoro'
+
+const stamp: OdoroPlugin = {
+  name: 'stamp',
+  transform: (code, { id }) => (id.endsWith('.tsx') ? code : null),
+  transformIndexHtml: (html) => html.replace('</head>', '<meta name="v"></head>'),
+  configureServer: ({ use }) => use((req, res, next) => next()),
+}
+
+export default defineConfig({ plugins: [stamp] })
+```
+
 ## The registry is not a dependency
 
 `odoro add text/count-up` **copies the source into your project**. The code is

package/client.d.ts

@@ -1,7 +1,7 @@
 /**
- * Types ambiants pour le code client d'un projet Odoro.
+ * Ambient types for the client code of an Odoro project.
  *
- * A referencer une fois dans le projet :
+ * To be referenced once in the project:
  *
  * ```ts
  * /// <reference types="odoro/client" />
@@ -10,37 +10,111 @@
  * @module
  */
 
-/** Variables d'environnement exposees au navigateur. */
+/** Environment variables exposed to the browser. */
 interface OdoroEnv {
-  /** Mode de compilation. */
-  readonly MODE: 'development' | 'production'
-  /** Vrai en developpement. */
+  /**
+   * Build mode.
+   *
+   * `development` and `production` are the two default modes, but a project can
+   * name others — `staging`, `demo` — and each reads its own `.env.<mode>`
+   * files.
+   */
+  readonly MODE: string
+  /** True in development. */
   readonly DEV: boolean
-  /** Vrai en production. */
+  /** True in production. */
   readonly PROD: boolean
-  /** Prefixe des URL publiques. */
+  /** True during prerendering, absent in the browser. */
+  readonly SSR?: boolean
+  /** Prefix of the public URLs. */
   readonly BASE_URL: string
-  /** Variables du projet portant le prefixe configure. */
+  /** Project variables carrying the configured prefix. */
   readonly [key: string]: string | boolean | undefined
 }
 
-/** API de rechargement a chaud exposee a chaque module. */
+/** Hot reloading API exposed to every module. */
 interface OdoroHot {
-  /** Donnees conservees d'une version de module a la suivante. */
+  /** Data kept from one module version to the next. */
   readonly data: Record<string, unknown>
-  /** Declare que ce module sait se remplacer a chaud. */
+  /** Declares that this module knows how to replace itself hot. */
   accept(callback?: (module: unknown) => void): void
-  /** Enregistre un nettoyage a executer avant le remplacement. */
+  /** Registers a cleanup to run before the replacement. */
   dispose(callback: (data: Record<string, unknown>) => void): void
-  /** Renonce au remplacement a chaud et recharge la page. */
+  /** Gives up hot replacement and reloads the page. */
   invalidate(): void
 }
 
 interface ImportMeta {
-  /** Variables d'environnement du projet. */
+  /** Environment variables of the project. */
   readonly env: OdoroEnv
-  /** Present uniquement en developpement. */
+  /** Present in development only. */
   hot?: OdoroHot
+
+  /**
+   * Imports every module matched by a pattern.
+   *
+   * The pattern is resolved at build time: what comes out of it is a table of
+   * static imports, whose keys are the paths as they were written.
+   *
+   * @example
+   * const pages = import.meta.glob('./pages/*.tsx')
+   * const module = await pages['./pages/home.tsx']?.()
+   */
+  glob<T = Record<string, unknown>>(
+    pattern: string | readonly string[],
+    options?: { eager?: false; import?: string },
+  ): Record<string, () => Promise<T>>
+
+  /**
+   * The same thing, but everything is loaded right away.
+   *
+   * @example
+   * const titles = import.meta.glob('./pages/*.tsx', { eager: true, import: 'title' })
+   */
+  glob<T = Record<string, unknown>>(
+    pattern: string | readonly string[],
+    options: { eager: true; import?: string },
+  ): Record<string, T>
+}
+
+/**
+ * The content of a file, as a string.
+ *
+ * @example
+ * import charter from './CHARTER.md?raw'
+ */
+declare module '*?raw' {
+  const content: string
+  export default content
+}
+
+/**
+ * The public address of a file, without loading it.
+ *
+ * @example
+ * import logo from './logo.svg?url'
+ */
+declare module '*?url' {
+  const address: string
+  export default address
+}
+
+/**
+ * A module to run in a separate worker.
+ *
+ * The class is constructed like any other `Worker`; the file is built apart and
+ * loaded as a module.
+ *
+ * @example
+ * import Compute from './compute.ts?worker'
+ * const worker = new Compute()
+ * worker.postMessage(21)
+ */
+declare module '*?worker' {
+  const Worker_: {
+    new (options?: WorkerOptions): Worker
+  }
+  export default Worker_
 }
 
 declare module '*.css' {

package/dist/build-XJIP4GNT.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+export { buildProject, reportBuild } from './chunk-DF67LADH.js';
+import './chunk-HS7NGZLM.js';
+import './chunk-RTWJ5GFB.js';
+import './chunk-7ZB5MAM6.js';

package/dist/{chunk-34RGOZFA.js → chunk-4D56Z7G3.js}

@@ -1642,11 +1642,11 @@ var CATEGORIES = [
   "ui",
   "section",
   /**
-   * Le rideau d'ouverture.
+   * The opening curtain.
    *
-   * Pas une section : une section occupe une place dans le flux de la page,
-   * un chargeur couvre l'ecran entier et disparait. Les ranger ensemble
-   * obligerait chaque section a declarer laquelle des deux elle est.
+   * Not a section: a section takes a place in the flow of the page, a loader
+   * covers the whole screen and disappears. Filing them together would force
+   * every section to declare which of the two it is.
    */
   "loader",
   "hooks"
@@ -1655,109 +1655,108 @@ var PERF_TIERS = ["light", "medium", "heavy"];
 var GL_BACKENDS = ["ogl", "three"];
 var FALLBACKS = ["poster", "gradient", "static", "none"];
 var fileSchema = object({
-  /** Chemin dans le dossier du composant. */
+  /** Path inside the component directory. */
   path: string2().check(_minLength(1)),
   /**
-   * Destination dans le projet, relative a l'alias de composants. Les chemins
-   * absolus et les remontees sont refuses : la CLI ecrit chez l'utilisateur,
-   * et un chemin non borne y serait une porte ouverte.
+   * Destination in the project, relative to the components alias. Absolute
+   * paths and climbs are refused: the CLI writes into the user project, and an
+   * unbounded path would be an open door.
    */
   target: string2().check(
     _minLength(1),
     refine((value) => !value.startsWith("/") && !value.includes(".."), {
-      error: "La destination doit rester relative et ne pas remonter dans l arborescence."
+      error: "The destination must stay relative and must not climb up the tree."
     })
   )
 });
 var engineSchema = object({
   /**
-   * Plugins d'orchestration requis. `core` designe la bibliotheque de base,
-   * toujours presente avec le moteur.
+   * Orchestration plugins required. `core` designates the base library, always
+   * present with the engine.
    */
   gsap: _default(array(string2().check(_minLength(1))), []),
-  /** Backend graphique requis, ou `false` si le composant n'en demande aucun. */
+  /** Graphics backend required, or `false` when the component asks for none. */
   gl: _default(union([literal(false), _enum(GL_BACKENDS)]), false)
 });
 var propSchema = object({
-  /** Nom de la propriete. */
+  /** Name of the property. */
   name: string2().check(_minLength(1)),
-  /** Type TypeScript, tel qu'il sera affiche dans la documentation. */
+  /** TypeScript type, as it will be shown in the documentation. */
   type: string2().check(_minLength(1)),
-  /** Obligatoire ou non. @defaultValue false */
+  /** Mandatory or not. @defaultValue false */
   required: _default(boolean2(), false),
-  /** Valeur par defaut, en representation source. */
+  /** Default value, in source form. */
   default: optional(union([string2(), number2(), boolean2()])),
   /**
-   * Unite de la valeur. Les durees sont **toujours** en millisecondes : c'est
-   * une regle du registre, pas une convention locale.
+   * Unit of the value. Durations are **always** in milliseconds: that is a rule
+   * of the registry, not a local convention.
    */
   unit: optional(string2()),
-  /** Explication affichee dans la table des proprietes. */
+  /** Explanation shown in the properties table. */
   description: optional(string2()),
   /**
-   * Bornes d'un reglage numerique.
+   * Bounds of a numeric setting.
    *
-   * Elles servent a la documentation, qui en fabrique un curseur. Sans elles,
-   * la page devrait redeclarer ce que le meta sait deja — et les deux
-   * divergeraient au premier changement de valeur par defaut.
+   * They serve the documentation, which makes a slider out of them. Without
+   * them, the page would have to redeclare what the meta already knows — and
+   * the two would diverge at the first change of default value.
    */
   min: optional(number2()),
   max: optional(number2()),
   step: optional(number2()),
-  /** Valeurs possibles d'un reglage a choix. */
+  /** Possible values of a choice setting. */
   options: optional(array(string2()))
 });
 var perfSchema = object({
-  /** Niveau de cout. */
+  /** Cost level. */
   tier: _enum(PERF_TIERS),
-  /** Backend graphique employe, s'il y en a un. */
+  /** Graphics backend used, when there is one. */
   backend: _default(union([literal(false), _enum(GL_BACKENDS)]), false),
-  /** Remarques affichees dans la documentation. */
+  /** Remarks shown in the documentation. */
   notes: optional(string2()),
   /**
-   * Nature du repli visuel. Obligatoire pour un composant couteux : le repli
-   * fait partie du composant, pas de sa documentation.
+   * Nature of the visual fallback. Mandatory for an expensive component: the
+   * fallback is part of the component, not of its documentation.
    */
   fallback: optional(_enum(FALLBACKS))
 });
 var baseSchema = object({
-  /** Identifiant, unique dans sa categorie. */
+  /** Identifier, unique within its category. */
   name: string2().check(
     _regex(/^[a-z0-9]+(-[a-z0-9]+)*$/, {
-      error: "Le nom doit etre en minuscules, avec des tirets pour separateurs."
+      error: "The name must be lowercase, with dashes as separators."
     })
   ),
-  /** Categorie. */
+  /** Category. */
   category: _enum(CATEGORIES),
-  /** Titre affiche. */
+  /** Displayed title. */
   title: string2().check(_minLength(1)),
-  /** Description affichee, en une phrase. */
+  /** Displayed description, in one sentence. */
   description: string2().check(_minLength(1)),
-  /** Ce que le composant demande au moteur. */
+  /** What the component asks of the engine. */
   engine: _default(engineSchema, { gsap: [], gl: false }),
-  /** Fichiers copies chez l'utilisateur. Au moins un. */
+  /** Files copied into the user project. At least one. */
   files: array(fileSchema).check(_minLength(1)),
-  /** Paquets npm a installer. */
+  /** npm packages to install. */
   dependencies: _default(array(string2().check(_minLength(1))), []),
   /**
-   * Autres entrees du registre dont celle-ci depend, sous la forme
-   * `categorie/nom`.
+   * Other registry entries this one depends on, in the form `category/name`.
    */
   registryDependencies: _default(
     array(
       string2().check(
         _regex(/^[a-z]+\/[a-z0-9]+(-[a-z0-9]+)*$/, {
-          error: 'Une dependance de registre s ecrit "categorie/nom".'
+          error: 'A registry dependency is written "category/name".'
         })
       )
     ),
     []
   ),
-  /** Variables CSS que le composant consomme. */
+  /** CSS variables the component consumes. */
   tokens: _default(array(string2().check(_startsWith("--o-"))), []),
-  /** Proprietes exposees. */
+  /** Properties exposed. */
   props: _default(array(propSchema), []),
-  /** Cout du composant. */
+  /** Cost of the component. */
   perf: perfSchema
 });
 var metaSchema = baseSchema.check(
@@ -1768,7 +1767,7 @@ var metaSchema = baseSchema.check(
         code: "custom",
         input: meta2,
         path: ["perf", "fallback"],
-        message: "Un composant de cout eleve doit declarer un repli visuel : il est affiche pendant le chargement, sans WebGL, et en mouvement reduit."
+        message: "A high-cost component must declare a visual fallback: it is shown while loading, without WebGL, and in reduced motion."
       });
     }
     if (meta2.perf.backend !== false && meta2.engine.gl !== meta2.perf.backend) {
@@ -1776,7 +1775,7 @@ var metaSchema = baseSchema.check(
         code: "custom",
         input: meta2,
         path: ["perf", "backend"],
-        message: `Le backend declare dans "perf" (${String(meta2.perf.backend)}) ne correspond pas a celui de "engine" (${String(meta2.engine.gl)}).`
+        message: `The backend declared in "perf" (${String(meta2.perf.backend)}) does not match the one of "engine" (${String(meta2.engine.gl)}).`
       });
     }
     if (meta2.engine.gl === "three" && meta2.perf.tier !== "heavy") {
@@ -1784,7 +1783,7 @@ var metaSchema = baseSchema.check(
         code: "custom",
         input: meta2,
         path: ["perf", "tier"],
-        message: "Un composant employant une scene 3D est necessairement de cout eleve."
+        message: "A component using a 3D scene is necessarily of high cost."
       });
     }
     const targets = meta2.files.map((file) => file.target);
@@ -1796,7 +1795,7 @@ var metaSchema = baseSchema.check(
         code: "custom",
         input: meta2,
         path: ["files"],
-        message: `Plusieurs fichiers visent la meme destination : ${[...new Set(duplicates)].join(", ")}.`
+        message: `Several files target the same destination: ${[...new Set(duplicates)].join(", ")}.`
       });
     }
   })
@@ -1819,9 +1818,9 @@ function parseMeta(value, origin) {
 // src/registry/resolve.ts
 function describeProblem(problem) {
   if (problem.kind === "cycle") {
-    return `Cycle de dependances : ${problem.path.join(" \u2192 ")}`;
+    return `Dependency cycle: ${problem.path.join(" \u2192 ")}`;
   }
-  return problem.requiredBy === null ? `Entree introuvable : ${problem.id}` : `Entree introuvable : ${problem.id}, reclamee par ${problem.requiredBy}`;
+  return problem.requiredBy === null ? `Entry not found: ${problem.id}` : `Entry not found: ${problem.id}, required by ${problem.requiredBy}`;
 }
 function resolveGraph(requested, available) {
   const problems = [];
@@ -1838,7 +1837,7 @@ function resolveGraph(requested, available) {
     }
     const entry = available.get(id);
     if (entry === void 0) {
-      problems.push({ kind: "introuvable", id, requiredBy });
+      problems.push({ kind: "missing", id, requiredBy });
       return;
     }
     path.push(id);

package/dist/{chunk-JMEHF3KN.js → chunk-7ZB5MAM6.js}

@@ -4,7 +4,7 @@ export { default as colors } from 'picocolors';
 
 var TAG = colors.bold(colors.magenta("odoro"));
 function stamp() {
-  return colors.dim((/* @__PURE__ */ new Date()).toLocaleTimeString("fr-FR", { hour12: false }));
+  return colors.dim((/* @__PURE__ */ new Date()).toLocaleTimeString("en-GB", { hour12: false }));
 }
 function info(message) {
   console.log(`${stamp()} ${TAG} ${message}`);
@@ -27,9 +27,9 @@ function duration(milliseconds) {
   return milliseconds < 1e3 ? `${Math.round(milliseconds)} ms` : `${(milliseconds / 1e3).toFixed(2)} s`;
 }
 function size(bytes) {
-  if (bytes < 1024) return `${bytes} o`;
-  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} Ko`;
-  return `${(bytes / (1024 * 1024)).toFixed(2)} Mo`;
+  if (bytes < 1024) return `${bytes} B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} kB`;
+  return `${(bytes / (1024 * 1024)).toFixed(2)} MB`;
 }
 
 export { duration, error, info, size, success, warn };