@tulipes/cli 0.1.1 → 0.2.0-rc.1

package/templates/AGENTS.md

@@ -16,22 +16,32 @@ one contract in depth.
 ## Preset scope
 
 Read the installed modules and package scripts before applying integration examples.
-The minimal preset has core, security and hello only. Auth, users, settings,
-MongoDB, Redis, queues, sockets, shared logger/cache helpers and PM2 examples
-below apply when those modules are installed (the production preset). Minimal
+The minimal preset has core, security, hello and agent only. Auth, users,
+config, settings, MongoDB, Redis, queues, sockets, shared logger/cache helpers
+and PM2 examples below apply when those modules are installed (the production
+preset). Minimal
 requests use the framework guest identity. Grant permissions to roles the app
 actually defines. Use the generated Vitest suite for changes; production tests
 require dedicated TEST_MONGO_URI and TEST_REDIS_URL services.
 
 ## Non-negotiable rules
 
-1. **Never read `process.env` directly.** Every configuration value is
-   declared in a module's `meta.variables.json` and read with
-   `ctx.Environment.get("NAME")`. Reading an undeclared name throws on
-   purpose. → skill `tulipes-env-variable`
+1. **Never read `process.env` directly, and keep the environment small.**
+   A value is an environment variable only if boot needs it before the
+   database answers (connection strings, the port, log destination) or it
+   is a secret: declared under `tulipes.env` in the module's `package.json`, read with
+   `ctx.Environment.get("NAME")`. Everything else is a *setting*: declared
+   with a zod schema in that module's `module.config.ts`, stored in the
+   settings store (the `settings` collection here; a JSON file under
+   `config/` in an app without the Mongo store), edited through the
+   console, read live at `ctx.config.<module>`. → skill `tulipes-env-variable`
 2. **A feature is a module, not a layer.** Everything a feature needs —
    routes, models, config, permissions, jobs — lives in one folder under
    `modules/`. Never add a top-level `services/` or `middlewares/` folder.
+   A module's root holds exactly `package.json`, `module.config.ts` and
+   `module.acl.ts`; everything else has a folder (`routes/`, `controllers/`,
+   `models/`, `schemas/`, `helpers/`, `bootstrap/`, `queues/`, `sockets/`,
+   `i18n/`, `agent/`, `lib/`, `tests/`), and the boot refuses a stray root file.
    → skill `tulipes-module`
 3. **Never call `mongoose.model()` yourself.** Models are declarations
    picked up by the framework and read from `ctx.models`. Persisted and
@@ -39,16 +49,23 @@ require dedicated TEST_MONGO_URI and TEST_REDIS_URL services.
    camelCase is for TypeScript-only names. → skill `tulipes-model`
 4. **Global middleware belongs to a sys-tier module**, not to the
    entrypoint. `app.ts` stays three lines. → skill `tulipes-endpoint`
-5. **Run `yarn sync` after touching any `meta.variables.json` or
-   `module.config.ts`.** It regenerates `types/config.d.ts` and
-   `.env.example`; stale generated types are a lie.
+5. **Run `pnpm sync` after touching a module's `tulipes.env`, a
+   settings schema in `module.config.ts`, a model file or a queue file's
+   `jobs` export.** It regenerates `types/tulipes.d.ts` and `.env.example`;
+   stale generated types are a lie. With it, `ctx.models.get("User")` is
+   typed from the model's schema and `queues.add("users.welcome", …)` from
+   the queue's job schema, so a wrong name or payload does not compile. `module.config.ts`
+   has exactly one export, `defineConfig({ schema })`; initialization and
+   cleanup belong to `bootstrap/*.bootstrap.ts`, which may return the
+   function that closes what it opened, and long-lived work ends on
+   `ctx.signal`.
 6. **Every response is `res.respond({ data, meta })`** — never `res.json`,
    which ships a raw body outside the envelope. Failures are **thrown**:
    `throw new HttpError(404, "notFound")`, where the message is an i18n
    key and the code derives from it. Never hand-roll an error shape.
    → skill `tulipes-response`
 7. **Every route declares a RAI**: put `rai({ id: "x:read" })` first in
-   each endpoint handler chain, including routes inside `defineRoutes()`.
+   each endpoint handler chain, including routes on a nested router.
    The id is also the ACL permission, and core refuses to boot if a route
    is missing one. Public is `acl.allow("guest", "x:read")`, never a
    missing check. → skill `tulipes-endpoint`
@@ -68,30 +85,47 @@ require dedicated TEST_MONGO_URI and TEST_REDIS_URL services.
     the auth module's `Credential` model, which is `select: false`.
 12. **When auth is installed, a new feature module's namespace goes in BOTH the `admin` and
     `sysadmin` grants** in `modules/auth/module.acl.ts`. Neither role holds
-    `*` — a wildcard would reach `settings:*` and make the sysadmin
-    boundary a label rather than a rule. → skill `tulipes-settings`
+    `*` — a wildcard would reach `config:write` and `settings:*` and make
+    the sysadmin boundary a label rather than a rule. → skills
+    `tulipes-config`, `tulipes-settings`
 13. **Cross-module imports use the package name** (`@app/users`,
     `@app/core`), never a relative path that climbs out of the module. The
     workspace boundary is what keeps modules independent, and a package
     name makes the dependency visible in package.json — declare it there
     and in `dependsOn`.
+14. **Every endpoint is a tool an agent can call; describe it as one.** The
+   `rai()` name, description and schemas are what the manifest shows, so a
+   bare `id` is a tool with no description. A module's `agent/*.agent.ts`
+   adds a summary, curates the routes and declares actions that are not
+   endpoints; `agent: false` on a `rai()` hides one. → skill
+   `tulipes-agent-tool`
+15. **A module's tests live in `modules/<name>/tests/` and boot the app
+   through `@tulipes/testing`**: `useTestApp({ rootDir }, { beforeAll,
+   afterAll })` once per file, `app.get(app.api("/x"))` with the envelope
+   decoded, `app.as("admin")` for a signed-in role. Never boot per test, and
+   never reach into another module's files from a test.
 
 For endpoint changes, read `tulipes-endpoint`: native routers live in
-`routes/*.routes.ts`. Use `defineRoutes()` and `runtime()` for offline inspection;
-keep shared middleware and param callbacks beside their endpoints.
+`routes/*.routes.ts`, plain `(ctx) => Router` functions: build the router from
+the context, return it for the configured prefix, and read models, settings
+and the environment inside handlers, never while building — `tulipes routes`
+and `tulipes spec` build every router with nothing acquired. Global
+middleware that needs the environment is built on its first request with
+`lazy()` from `@app/core`.
 
 ## Where things go
 
 | Decision | Location |
 |---|---|
-| Value differs per deployment (URL, secret, toggle) | that module's `meta.variables.json` |
-| Policy shared by ≥2 modules (pagination, body limit) | `config/app.config.ts` |
-| Config for one feature | that module's `module.config.ts` |
+| Connection string, secret, or anything boot needs before the database answers | `tulipes.env` in that module's `package.json` |
+| Policy shared by ≥2 modules and the same everywhere (pagination, locales) | `config/app.config.ts` |
+| A value an operator may change at runtime (limits, modes, toggles, lifetimes) | a field in that module's `module.config.ts` schema, read at `ctx.config.<module>` |
+| Opening a client, seeding rows, ensuring indexes, and closing them again | that module's `bootstrap/*.bootstrap.ts`, returning the cleanup |
 | A string a user will read | that module's `i18n/<locale>.json`, reached with `req.t` |
 | The shape of a request body/query | a zod schema on the route's `rai()` |
 | Middleware for every request | a sys-tier module's routes file |
 | Middleware for one feature's routes | that module's own `Router` |
-| Helper used by ≥2 modules | the sys core module, exported from its `index.ts` and imported as `@app/core` |
+| Helper used by ≥2 modules | the sys core module, exported from its `lib/index.ts` and imported as `@app/core` |
 | Helper used by one module | that module's `helpers/` |
 | One-off task (backfill, export, admin chore) | `scripts/`, booted with `mode: "script"` |
 | Anything you would `console.log` | `moduleLogger(ctx.Environment, "<module>", ctx.mode)` from `@app/core` |
@@ -99,27 +133,30 @@ keep shared middleware and param callbacks beside their endpoints.
 ## Boot order (why load order matters)
 
 `sys` modules load before `app` modules; within a tier, lower `priority`
-first; then `dependsOn` topological order. Config → translations → ACL →
-database → queues → routes. If code needs something another module
-provides, declare `dependsOn` — do not rely on luck.
+first; then `dependsOn` topological order. Declarations → models →
+settings → translations → ACL → bootstrap → queues → routes. If code needs
+something another module provides, declare `dependsOn` — do not rely on
+luck.
 
 ## Commands
 
 | Command | Use |
 |---|---|
-| `yarn dev` | run the backend process (regenerates types first) |
-| `yarn worker` | run the queue-consumer process |
-| `yarn sync` | regenerate `types/config.d.ts` + `.env.example` |
-| `yarn check` | validate the environment without booting |
-| `yarn typecheck` | typecheck the whole app |
-| `yarn tulipes new module <name>` | scaffold a module |
+| `pnpm dev` | run the backend process (regenerates types first) |
+| `pnpm worker` | run the queue-consumer process |
+| `pnpm sync` | regenerate `types/tulipes.d.ts` + `.env.example` |
+| `pnpm tulipes agent manifest [--role r]` | print every tool the app exposes to agents, offline |
+| `pnpm test` | every `tests/` and `modules/*/tests/` file; each boots the app once through `@tulipes/testing` |
+| `pnpm check` | validate the environment without booting |
+| `pnpm typecheck` | typecheck the whole app |
+| `pnpm tulipes new module <name>` | scaffold a module |
 | `tulipes update` | upgrade the global cli and the framework in every manifest |
-| `yarn script scripts/x.ts` | run a one-off script against the real app |
+| `pnpm script scripts/x.ts` | run a one-off script against the real app |
 
 ## Verifying your work
 
-A change is not done until the app boots. Run `yarn typecheck`, then
-`yarn dev` and confirm the startup banner lists what you added (modules,
+A change is not done until the app boots. Run `pnpm typecheck`, then
+`pnpm dev` and confirm the startup banner lists what you added (modules,
 queues, sockets, roles). Boot failures print an aggregate report naming
 every problem at once — read all of it before fixing anything. → skill
 `tulipes-boot-errors`

package/templates/CLAUDE.md

@@ -6,7 +6,8 @@ here; it holds the non-negotiable rules, where each kind of code belongs, the
 boot order and the commands.
 
 This file exists so Claude Code picks that up automatically. The other
-Claude-specific piece is `.claude/skills/`: eight task-scoped guides — module,
-environment variable, endpoint, model, queue, socket, permissions and reading
-boot errors — loaded on demand when a task matches one. AGENTS.md points at
-them by name.
+Claude-specific piece is `.claude/skills/`: task-scoped guides — module,
+environment variable, endpoint, response, model, queue, socket, permissions,
+settings (the config module and the log stream), i18n, spec, agent tools and
+reading boot errors — loaded on demand when a task matches one. AGENTS.md
+points at them by name.

package/templates/app/.envs/.env.development

@@ -0,0 +1,18 @@
+# Development. NOT committed — .gitignore excludes .envs/, because a
+# file holding working credentials does not belong in a repository.
+# The committed contract is .env.example at the root: copy it here and
+# fill it in. Real deployments inject variables through the container
+# environment, which always wins over this file.
+
+PORT=3000
+LOG_LEVEL=debug
+
+MONGO_URI=mongodb://127.0.0.1:27017/tulipes-example
+REDIS_URL=redis://127.0.0.1:6379
+
+# Auth. Separate keys, so leaking one cannot mint the other.
+JWT_ACCESS_SECRET=dev-only-access-secret-change-me
+JWT_REFRESH_SECRET=dev-only-refresh-secret-change-me
+AUTH_ADMIN_EMAIL=admin@example.com
+AUTH_ADMIN_PASSWORD=dev-admin-password
+

package/templates/app/.envs/.env.production

@@ -0,0 +1,19 @@
+# Production. NOT committed — .gitignore excludes .envs/. Recreate it
+# on the deployment host from .env.example, or leave it out entirely
+# and inject everything through the container environment.
+#
+# The blanks below are intentional. Real deployments inject MONGO_URI,
+# REDIS_URL and any secret through the container environment, which
+# always wins over this file. Booting without them fails closed with a
+# report naming every missing variable — run `pnpm check` to see it
+# without starting the app.
+
+PORT=3000
+LOG_LEVEL=info
+
+# MONGO_URI=
+# REDIS_URL=
+# JWT_ACCESS_SECRET=
+# JWT_REFRESH_SECRET=
+# AUTH_ADMIN_EMAIL=
+# AUTH_ADMIN_PASSWORD=

package/templates/app/.envs/.env.staging

@@ -0,0 +1,19 @@
+# Staging. NOT committed — .gitignore excludes .envs/. Recreate it on
+# the deployment host from .env.example, or leave it out entirely and
+# inject everything through the container environment.
+#
+# The blanks below are intentional. Real deployments inject MONGO_URI,
+# REDIS_URL and any secret through the container environment, which
+# always wins over this file. Booting without them fails closed with a
+# report naming every missing variable — run `pnpm check` to see it
+# without starting the app.
+
+PORT=3000
+LOG_LEVEL=info
+
+# MONGO_URI=
+# REDIS_URL=
+# JWT_ACCESS_SECRET=
+# JWT_REFRESH_SECRET=
+# AUTH_ADMIN_EMAIL=
+# AUTH_ADMIN_PASSWORD=

package/templates/app/README.md

@@ -0,0 +1,327 @@
+# tulipes-example
+
+A production-preset [Tulipes](https://www.npmjs.com/package/@tulipes/core) application. Requires Node 24.x.
+
+## Run
+
+```sh
+npm install -g pnpm   # once per machine
+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.
+
+`.envs/` is git-ignored: those files hold working credentials. On a
+fresh clone there is nothing in it, so copy `.env.example` — which is
+committed, and which `pnpm sync` regenerates from every module's
+declared variables — and fill it in:
+
+```sh
+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
+```
+
+## Verify
+
+Run `pnpm sync`, `pnpm typecheck` and `pnpm check`. Tests need dedicated
+services: `TEST_MONGO_URI=mongodb://127.0.0.1:27017/tulipes_tests TEST_REDIS_URL=redis://127.0.0.1:6379/3 pnpm test`.
+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.
+Staging/production boot rejects development credentials and equal JWT keys.
+Auth, settings and deployment examples are application policy you own.
+
+## The hello module
+
+`modules/hello` is a worked example of every module contract — read it
+before writing your own:
+
+| File | Contract |
+|---|---|
+| `package.json` `tulipes.env` | the module's environment contract |
+| `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 |
+| `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 -->
+| `models/*.model.ts` | a schema declaration for the model store |
+| `bootstrap/*.bootstrap.ts` | idempotent seeding, before traffic |
+| `queues/*.queues.ts` | a job definition and its processor | <!-- feature:queues -->
+
+## Daily commands
+
+| command | does |
+|---|---|
+| `pnpm dev` | regenerate types, run the backend process with `node --watch` |
+| `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 update` | upgrade the framework everywhere it is declared |
+
+## Authentication
+
+`modules/auth` is sys tier, so it resolves the caller before any
+feature route runs. A request with no valid token is not rejected — it
+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
+```
+
+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":
+
+```ts
+router.get(
+  `${base}/invoices`,
+  rai({ id: "invoices:read", name: "List invoices" }),
+  billing.list(),
+);
+```
+
+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
+roles that reach it.
+
+Try it — the admin comes from AUTH_ADMIN_EMAIL / AUTH_ADMIN_PASSWORD:
+
+```sh
+curl -X POST localhost:3000/api/v1/auth/login \
+  -H 'content-type: application/json' \
+  -d '{"email":"admin@example.com","password":"dev-admin-password"}'
+
+curl localhost:3000/api/v1/auth/me -H "authorization: Bearer <accessToken>"
+```
+
+Inside a handler, the caller is `req.auth` — resolved before any
+feature route and never undefined inside a declared one:
+
+```ts
+const { isAuthenticated, user, session } = req.auth;
+user?.email          // the hydrated user document, null for a guest
+session?.sid         // this device's session row, null for a guest
+```
+
+Never re-parse the Authorization header: the pipeline already did. It
+resolves the session and the user on every request — from the app cache
+(Redis, shared by every replica) when a request resolved them recently,
+from the database otherwise — and every path that revokes (logout,
+refresh reuse, password change, a session ended, a deleted account)
+forgets the cached entry first, so a demotion, a ban or a logout takes
+effect on the very next request on any replica. Code that writes a
+user's role calls `forgetUser()` from `@app/auth` for the same reason.
+
+Sessions are rows, so a signed-in account can see and end its own
+devices — `GET /auth/sessions`, `DELETE /auth/sessions/:sid`. Ending
+one takes effect on the next request that device makes, even though
+its access token is still signed and unexpired.
+
+Passwords never touch the User document: the hash lives in the auth
+module's `Credential` model, `select: false`, so a route that
+serialises a user cannot leak one. Refresh tokens rotate on use;
+logout deletes the refresh row and blacklists the access token's jti
+until it expires; a password change moves a per-user epoch that
+invalidates every token issued before it. Both token collections carry
+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
+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)
+before it lands, applied at once in every replica. Reading needs `admin`;
+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.
+
+## Logging
+
+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);
+log.info({ invoiceId }, "invoice sent");
+```
+
+It writes to two destinations at once, because they answer different
+questions: a **coloured, human-readable** stream on the console, and
+**JSON lines** in `logs/` — one object per line, which is what makes
+them greppable with jq or ingestible by a collector. Errors are
+additionally copied to their own file, so the first thing to open when
+something breaks is small.
+
+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 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`
+can watch the files live: `GET /api/v1/settings/logs/stream` (SSE).
+
+## Responses
+
+Every endpoint answers with one envelope, so a client unwraps once:
+
+```jsonc
+{ "success": true, "data": { }, "errors": [], "meta": {} }
+```
+
+`res.respond` builds it. Express is untouched — `res.json` and
+`res.status` behave exactly as they always did:
+
+```ts
+res.respond({ data: user });
+res.respond({ data: user, status: 201 });
+res.respond({ data: items, meta: { total_items } });   // paginated
+```
+
+Failures are **thrown**, never responded — the framework's terminal
+handler builds the same envelope from them, so a handler only writes
+the happy path. The message is an i18n key: it gets translated in the
+module's namespace and the error code is derived from it.
+
+```ts
+throw new HttpError(404, "notFound");                   // → NOT_FOUND
+throw new HttpError(422, "emailTaken", { field: "email" });
+```
+
+`req.page` is already parsed from `?page` / `?per_page` and clamped
+by `config.pagination`; passing `total_items` is what marks a
+response as a page and fills in `total_pages`.
+
+In development, a route answering without `res.respond` logs a
+warning naming it.
+
+## Browser authentication
+
+Read [Browser authentication and cookies](docs/browser-auth.md) before wiring
+up a browser client. The starter uses Bearer headers and JSON refresh tokens;
+CORS settings do not install cookie authentication or CSRF protection.
+
+## Translations
+
+Each module owns its strings and IS its own i18n namespace:
+`modules/hello/i18n/en.json`, `fr.json`. Inside an endpoint `req.t`
+is already bound to the module that declared the route — `rai()` binds
+it — so there is nothing to import and no namespace to name:
+
+```ts
+res.json({ message: req.t("created", { email }) });
+throw new HttpError(404, req.t("notFound"));
+```
+
+The locale is `?lang=fr`, else Accept-Language, else
+`config.i18n.defaultLocale` — narrowed to `supportedLocales`:
+
+```sh
+curl 'localhost:3000/api/v1/hello/secret?lang=fr' -H "authorization: Bearer <token>"
+```
+
+Code with no request names both: `ctx.t("users", recipient.locale)`,
+which is how a queue processor translates against the recipient's
+locale rather than the enqueuer's — so put the locale in the job.
+
+Only the default locale must be complete. Anything another locale
+lacks falls back to it and is listed in `<locale>.missing.json` beside
+it on the next boot — git-ignored, and never written in production.
+
+## Scripts
+
+`scripts/` holds one-off tasks — backfills, exports, admin chores.
+They boot the app in **script mode**, which runs every phase the
+backend runs and then starts no server, so a script gets exactly what
+a route handler gets: config, ACL, models, queue producers.
+
+```sh
+pnpm script scripts/count-greetings.ts
+```
+
+Copy the try/finally from `scripts/count-greetings.ts`: mongo and
+redis hold the event loop open, so a script that forgets
+`handle.shutdown()` prints its output and then hangs.
+
+## Deploying nginx
+
+`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:
+
+```sh
+APP_ENV=production pnpm script scripts/deploy-nginx.ts --dry-run
+sudo -E APP_ENV=production pnpm script scripts/deploy-nginx.ts
+```
+
+It writes `sites-available/<domain>`, links `sites-enabled`, runs
+`nginx -t`, then reloads. It refuses when not root, while
+`core.publicDomain` is still `localhost`, or when the conf already exists
+(pass `--force` to overwrite one). Debian/Ubuntu layout.
+
+The rendered conf is HTTP-only with the TLS block commented out —
+`nginx -t` fails on certificate paths that do not exist yet, which
+would make the first deploy impossible. Install the certificate,
+uncomment the block, redeploy with `--force`.
+
+## Running under PM2
+
+`ecosystem.config.cjs` defines both processes — the backend and the
+queue worker — in all three modes:
+
+```sh
+pnpm pm2:start              # development
+pnpm pm2:start:staging
+pnpm pm2:start:production
+
+pnpm pm2:status             # what is running
+pnpm pm2:logs               # tail both processes
+pnpm pm2:restart            # reload code
+pnpm pm2:stop               # stop, keep them in the process list
+pnpm pm2:delete             # remove from the process list
+```
+
+Switching environment requires a restart carrying the flag, because
+PM2 remembers the environment a process was started with:
+`pm2 restart ecosystem.config.cjs --env production`.
+
+`.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.
+
+PM2 is a devDependency so the scripts work straight after install;
+servers usually install it globally instead (`npm i -g pm2`), in
+which case the same scripts still work.
+
+Two defaults worth knowing: processes run in **fork** mode with a
+single instance, because Socket.IO needs sticky sessions or the Redis
+adapter before a second instance is safe; and `kill_timeout` is 10s so
+graceful shutdown can drain queues and close mongo and redis before
+PM2 sends SIGKILL.

package/templates/app/app.ts

@@ -0,0 +1,3 @@
+import { boot } from "@tulipes/core/boot";
+
+await boot({ rootDir: import.meta.dirname, mode: "backend" });

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

@@ -0,0 +1,73 @@
+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
+ * whatever it returns becomes the base of the global config. Modules read
+ * it through `ctx.config.<key>`.
+ *
+ * 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.
+ *
+ * The framework reads exactly one field of this object: `app.name`, which
+ * titles the startup banner. Everything else is yours.
+ */
+
+// `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 = (() => ({
+  app: {
+    name: "tulipes-example",
+  },
+
+  /**
+   * Route prefixing. A router a routes file returns is mounted under this
+   * prefix, so versioning the whole API is a one-line change here; a module
+   * that wants another path says so with `ctx.routes.mount(router, "/x")`.
+   */
+  api: {
+    prefix: "/api/v1",
+  },
+
+  /**
+   * The languages this app speaks. Every module owns its own strings in
+   * `modules/<name>/i18n/<locale>.json` — the module is the namespace —
+   * and `req.t` inside an endpoint is already bound to the module that
+   * declared it. A request picks its locale with `?lang=fr` or an
+   * Accept-Language header, narrowed to this list.
+   *
+   * `defaultLocale` is also the fallback: a key missing from fr.json is
+   * served from en.json, and outside production the gap is recorded in
+   * `fr.missing.json` next to it.
+   */
+  i18n: {
+    defaultLocale: "en",
+    supportedLocales: ["en", "fr"],
+  },
+
+  /**
+   * List-endpoint defaults, so every module paginates identically and no
+   * caller can ask for ten thousand rows. → modules/users/routes
+   */
+  pagination: {
+    defaultLimit: 20,
+    maxLimit: 100,
+  },
+})) satisfies AppConfigFn;
+
+export default appConfig;
+
+/**
+ * Types these keys at every call site: `config.pagination!.maxLimit` is a
+ * 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.
+ */
+declare module "@tulipes/core/config" {
+  interface GlobalConfig extends Partial<ReturnType<typeof appConfig>> {}
+}