@tulipes/cli 0.2.0-rc.2 → 0.3.0-rc.2

package/templates/app/README.md

@@ -10,9 +10,10 @@ pnpm install
 pnpm dev          # boot the backend process → http://localhost:3000/api/v1/hello
 ```
 
-Needs mongo and redis running — see `MONGO_URI` and `REDIS_URL` in
-`.envs/.env.development`. Run `pnpm worker` in a second terminal to
-consume queued jobs.
+Needs mongo and redis running — see `MONGO_URI` (or the `MONGO_HOST`,
+`MONGO_USERNAME`, `MONGO_PASSWORD` and `MONGO_DBNAME` parts) and
+`REDIS_URL` in `.envs/.env.development`. Run `pnpm worker` in a second
+terminal to consume queued jobs.
 
 `.envs/` is git-ignored: those files hold working credentials. On a
 fresh clone there is nothing in it, so copy `.env.example` — which is
@@ -23,7 +24,7 @@ declared variables — and fill it in:
 pnpm sync                              # refresh .env.example and types
 mkdir -p .envs                         # git does not track empty dirs
 cp .env.example .envs/.env.development
-pnpm check                             # validate it without booting
+pnpm check                             # resolve it without booting, and see where each value lands
 ```
 
 ## Verify
@@ -33,7 +34,8 @@ services: `TEST_MONGO_URI=mongodb://127.0.0.1:27017/tulipes_tests TEST_REDIS_URL
 Use test-only data: the suite creates users and sessions. `pnpm spec` writes
 OpenAPI/Postman documents offline, without services or runtime secrets.
 Change the shared API prefix in `config/routes.ts`. Runtime middleware stays
-with endpoints in `routes/*.routes.ts`, plain functions of the context.
+with endpoints in `routes/`, plain functions of the context, named
+scope-first (`routes/web.users.routes.ts`, `routes/bo.users.routes.ts`).
 Staging/production boot rejects development credentials and equal JWT keys.
 Auth, settings and deployment examples are application policy you own.
 
@@ -44,11 +46,11 @@ before writing your own:
 
 | File | Contract |
 |---|---|
-| `package.json` `tulipes.env` | the module's environment contract |
+| `package.json` `tulipes.env` | the module's environment values, read at `ctx.config.hello.<name>` (hello declares none) |
 | `module.config.ts` | `defineConfig({ schema })`: this module's settings |
-| `module.acl.ts` | permission grants on `hello:*` |
-| `routes/*.routes.ts` | native routers, shared middleware and RAI schemas |
-| `controllers/` | the work; constructed from the context while routes build |
+| `module.acl.ts` | permission grants on `hello:web:*` ids, with prefix wildcards |
+| `routes/web/*.routes.ts` | native routers, shared middleware and RAI schemas; one folder per scope |
+| `controllers/web/` | the work; constructed from the context while routes build |
 | `helpers/` | pure logic, no framework |
 | `i18n/<locale>.json` | this module's strings — the module is the namespace |
 | `sockets/*.sockets.ts` | a claimed Socket.IO namespace | <!-- feature:sockets -->
@@ -64,7 +66,9 @@ before writing your own:
 | `pnpm worker` | run the queue-consumer process (needs a queue first) | <!-- feature:queues -->
 | `pnpm sync` | regenerate `types/tulipes.d.ts` + `.env.example` |
 | `pnpm check` | validate env against every module contract — CI gate |
-| `pnpm tulipes new module <name>` | scaffold a module |
+| `pnpm tulipes new module <name>` | scaffold a module (`--scope bo` for the back office) |
+| `pnpm tulipes routes` | every endpoint and the roles that reach it (`--scope bo` for one surface) |
+| `pnpm tulipes roles` | every role, its description and the grants it holds |
 | `pnpm tulipes update` | upgrade the framework everywhere it is declared |
 
 ## Authentication
@@ -75,21 +79,29 @@ becomes the **guest** caller, which is what makes a public endpoint
 an ordinary ACL grant instead of a second mechanism:
 
 ```ts
-acl.allow("guest", "auth:login");   // that is why login is reachable
+acl.allow("guest", "auth:web:login");   // that is why login is reachable
 ```
 
 Guarding is the RAI itself — its `id` IS the permission, so there is
-no second call to forget. 401 means "sign in"; 403 means "signed in,
-still not allowed":
+no second call to forget. An id is always `module:scope:resource[:extra]`:
+`users:web:list`, `users:bo:list:deleted`. 401 means "sign in"; 403 means
+"signed in, still not allowed":
 
 ```ts
 router.get(
   `${base}/invoices`,
-  rai({ id: "invoices:read", name: "List invoices" }),
+  rai({ id: "billing:web:invoices", name: "List invoices" }),
   billing.list(),
 );
 ```
 
+Roles are defined once in `modules/auth/module.acl.ts`, each with a
+description and any extra the app reads back (`level` here):
+
+```ts
+acl.defineRole("admin", { description: "Runs the back office", level: 2 });
+```
+
 A route that declares no RAI would be reachable by guest, so core
 scans the router stack after mounting and refuses to boot when it
 finds one. Run `pnpm tulipes routes` to see every endpoint with the
@@ -139,8 +151,9 @@ TTL indexes.
 ## The console
 
 `modules/config` is the operator's console: `GET /api/v1/config`
-describes every module — manifest, declared variables (names, types and
-sources; a secret's value never), settings with their schema, live values
+describes every module — manifest, environment values (config name,
+variable, type and source; a secret's value never), settings with their
+schema, live values
 and stored version, endpoints with the roles that reach them — and
 `PATCH /api/v1/config/:module` changes a module's settings: validated by
 its schema, refused on a stale version, audited (names, never values)
@@ -149,7 +162,7 @@ writing needs `sysadmin`. Settings live in MongoDB (`settings` and
 `settings_history`) because the root `package.json` declares
 `@tulipes/mongoose/settings`; the request pipeline — proxy trust, CORS,
 HSTS, the body limit, the rate limits — is configured from
-`config.security` this way, so none of it is an environment variable.
+`config.security` this way, so none of it is an environment value.
 
 ## Logging
 
@@ -158,7 +171,7 @@ The logger lives in the core module and is shared by every other one:
 ```ts
 import { moduleLogger } from "@app/core";
 
-const log = moduleLogger(ctx.Environment, "billing", ctx.mode);
+const log = moduleLogger(ctx, "billing");
 log.info({ invoiceId }, "invoice sent");
 ```
 
@@ -173,9 +186,10 @@ Files carry the process mode — `app-backend.log`, `app-worker.log` —
 because backend and worker run at the same time and two processes
 rotating one file will race.
 
-The destinations are environment, because the logger exists before the
-settings store answers: `LOG_LEVEL`, `LOG_CONSOLE`, `LOG_FILE` and
-`LOG_DIR`, declared in `modules/core/package.json`. The file names and
+The destinations are environment values, because the logger exists before
+the settings store answers: `LOG_LEVEL`, `LOG_CONSOLE`, `LOG_FILE` and
+`LOG_DIR`, declared in `modules/core/package.json` and read as
+`config.core.logLevel`, `logConsole`, `logFile` and `logDir`. The file names and
 the rotation (daily or 20m, whichever trips first; fourteen rotated
 files kept) never needed to differ per deployment, so they are the
 `LOG_FILES` constants in `modules/core/helpers/logger/`. A `sysadmin`
@@ -268,8 +282,8 @@ redis hold the event loop open, so a script that forgets
 `nginx/{development,staging,production}.conf` are templates with
 `{{DOMAIN}}` and `{{PORT}}` placeholders. The deploy script renders
 the one matching `APP_ENV`, using that same environment's
-the `core.publicDomain` setting and `PORT`, so template, domain and port can never
-disagree:
+`core.publicDomain` setting and the port `config/app.config.ts` wired from
+`PORT`, so template, domain and port can never disagree:
 
 ```sh
 APP_ENV=production pnpm script scripts/deploy-nginx.ts --dry-run
@@ -309,12 +323,13 @@ PM2 remembers the environment a process was started with:
 
 `.envs/` holds one file per mode and is **git-ignored** — those files
 carry working credentials. What is committed is `.env.example`,
-generated by `pnpm sync`, naming every variable any module declares:
-a clone copies it into `.envs/.env.<mode>` and fills it in. Servers
-usually skip the file entirely and inject variables through the
-container environment, which always wins over it. `pnpm check`
-validates the current environment without booting, so a deploy can
-fail on configuration before it fails on traffic.
+generated by `pnpm sync`, naming every variable any module declares
+and the `config.<module>.<name>` it lands on: a clone copies it into
+`.envs/.env.<mode>` and fills it in. Servers usually skip the file
+entirely and inject variables through the container environment, which
+always wins over it. `pnpm check` resolves the current environment
+without booting, so a deploy can fail on configuration before it fails
+on traffic.
 
 PM2 is a devDependency so the scripts work straight after install;
 servers usually install it globally instead (`npm i -g pm2`), in

package/templates/app/config/app.config.ts

@@ -3,24 +3,35 @@ import type { AppConfigFn } from "@tulipes/core/boot";
 /**
  * ── The app-wide config seed ──────────────────────────────────────────
  *
- * Runs FIRST in boot phase 6, before any module.config.ts factory, and
+ * Runs FIRST in boot phase 4, before any module's settings are loaded, and
  * whatever it returns becomes the base of the global config. Modules read
  * it through `ctx.config.<key>`.
  *
+ * It receives `env`: every module's environment values, resolved from the
+ * container, `.envs/.env.<APP_ENV>` and the defaults each module declares
+ * in its package.json `tulipes.env` — `env.core.port`, `env.auth.adminEmail`
+ * — typed by `pnpm sync`. This is the one place the environment is wired
+ * to what the framework and the providers read: `server.port` for core,
+ * `mongoose.*` for @tulipes/mongoose, `bullmq.redisUrl` for @tulipes/bullmq.
+ * Modules never need this wiring: each reads its own values as
+ * `ctx.config.<module>.<name>`, beside its settings.
+ *
  * Add a key here when two or more modules share a value. Config belonging
  * to ONE feature goes in that module's `module.config.ts` instead, where
  * `pnpm sync` types it for you — that is where `users.maxSessions` and
  * `users.signupMode` live. A value that differs per deployment belongs in
- * neither: declare it in a module's `meta.variables.json` and read it with
- * `Environment.get`, the way MONGO_URI, CORS_ORIGINS and BODY_LIMIT do.
+ * neither: declare it under `tulipes.env` in a module's package.json and
+ * read it as `ctx.config.<module>.<name>`, the way MONGO_URI and REDIS_URL
+ * are declared by the core module.
  *
- * The framework reads exactly one field of this object: `app.name`, which
- * titles the startup banner. Everything else is yours.
+ * Under inspection (`tulipes routes`, `tulipes spec`) a value that is
+ * missing or invalid is `undefined` rather than an error, so this file
+ * only wires values and never requires one.
  */
 
 // `satisfies` (not a type annotation) so TypeScript keeps the exact shape
 // of this object for the augmentation at the bottom of the file.
-const appConfig = (() => ({
+const appConfig = ((env) => ({
   app: {
     name: "tulipes-example",
   },
@@ -34,6 +45,31 @@ const appConfig = (() => ({
     prefix: "/api/v1",
   },
 
+  /** What core listens on. */
+  server: {
+    port: env.core.port,
+  },
+
+  /**
+   * How @tulipes/mongoose reaches MongoDB. A full MONGO_URI wins — it is the
+   * only way to name a replica set, an Atlas cluster or driver options;
+   * otherwise the host, credentials and database name are handed to the
+   * driver separately, so nothing is URL-encoded by hand.
+   */
+  mongoose: env.core.mongodbUri
+    ? { uri: env.core.mongodbUri }
+    : {
+        uri: env.core.mongodbHost,
+        user: env.core.mongodbUsername,
+        pass: env.core.mongodbPassword,
+        dbName: env.core.mongodbDbName,
+      },
+
+  /** How @tulipes/bullmq reaches Redis. */
+  bullmq: {
+    redisUrl: env.core.redisUrl,
+  },
+
   /**
    * The languages this app speaks. Every module owns its own strings in
    * `modules/<name>/i18n/<locale>.json` — the module is the namespace —
@@ -50,6 +86,21 @@ const appConfig = (() => ({
     supportedLocales: ["en", "fr"],
   },
 
+  /**
+   * How instants are read. Dates are stored and returned as UTC; a zone is
+   * what "today", "02:00" and a timestamp in an email mean. A request picks
+   * its own with `?tz=Europe/Paris` or an X-Timezone header (narrowed to
+   * `supported` when you list it), and handlers read it as `req.timezone`
+   * with helpers on `req.time`; code with no request uses `ctx.time`.
+   *
+   * `default` is also the zone of cron patterns given to `ctx.queues`, and
+   * — unless `applyToProcess: false` — the process zone, so log times,
+   * daily log rotation and `Date#getHours()` agree with it.
+   */
+  timezone: {
+    default: "UTC",
+  },
+
   /**
    * List-endpoint defaults, so every module paginates identically and no
    * caller can ask for ten thousand rows. → modules/users/routes
@@ -67,7 +118,9 @@ export default appConfig;
  * number, not `unknown`. `pnpm sync` does this automatically for
  * module.config.ts factories; the app-level seed types itself here.
  * Partial because the config object is empty until this factory runs.
+ * `server`, `mongoose` and `bullmq` are left out: core and the providers
+ * already type the keys they read.
  */
 declare module "@tulipes/core/config" {
-  interface GlobalConfig extends Partial<ReturnType<typeof appConfig>> {}
+  interface GlobalConfig extends Partial<Omit<ReturnType<typeof appConfig>, "server" | "mongoose" | "bullmq">> {}
 }