@tulipes/core 0.1.10 → 0.1.12

package/dist/cli/init.js

@@ -245,155 +245,56 @@ function renderProject(name, coreVersion) {
                 ` * ── 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. Every`,
-                ` * module then reads it through \`ctx.config.<key>\`:`,
+                ` * whatever it returns becomes the base of the global config. Modules`,
+                ` * read it through \`ctx.config.<key>\`:`,
                 ` *`,
-                ` *   export default function usersRoutes({ config }: Ctx) {`,
-                ` *     const router = Router();`,
-                ` *     router.get(\`\${config.api!.prefix}/users\`, handler);`,
-                ` *   }`,
+                ` *   router.get(\`\${config.api!.prefix}/users\`, handler);`,
                 ` *`,
-                ` * The framework itself reads exactly ONE field: \`app.name\`, for the`,
-                ` * startup banner. Everything else below is convention — YOUR keys, read`,
-                ` * by YOUR modules. Rename them, delete them, invent new ones freely;`,
-                ` * nothing in core depends on them.`,
+                ` * 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 \`yarn sync\` types it for you. 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.`,
                 ` *`,
-                ` * Config that belongs to one feature does NOT go here — it goes in that`,
-                ` * module's \`module.config.ts\`, where codegen types it automatically.`,
-                ` * This file is for values two or more modules share.`,
-                ` *`,
-                ` * Values can be hardcoded (below) or driven by the environment. To make`,
-                ` * any of them env-driven, declare the variable in a module's`,
-                ` * meta.variables.json first, then read it here with`,
-                ` * \`Environment.get("NAME")\` — reads of undeclared variables throw on`,
-                ` * purpose, so a typo can never boot.`,
+                ` * 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 = ((Environment) => ({`,
-                `  /**`,
-                `   * Identity. \`name\` is the one field core consumes — it titles the`,
-                `   * startup banner ("▲ ${name}"). The rest is yours: stamp \`version\``,
-                `   * into a /health payload, switch behaviour on \`env\`, etc.`,
-                `   */`,
+                `const appConfig = (() => ({`,
                 `  app: {`,
                 `    name: ${JSON.stringify(name)},`,
-                `    version: "0.1.0",`,
-                `    description: "A Tulipes API",`,
-                `    // development | staging | production | test — resolved from APP_ENV`,
-                `    env: Environment.appEnv,`,
-                `    // Read a declared variable (PORT lives in modules/core/meta.variables.json)`,
-                `    port: Environment.get("PORT"),`,
                 `  },`,
                 ``,
                 `  /**`,
-                `   * Route prefixing. Modules build their paths from this instead of`,
+                `   * Route prefixing. Modules build paths from this instead of`,
                 `   * hardcoding "/api/v1", so versioning the whole API is a one-line`,
-                `   * change here: \`router.get(\\\`\${config.api!.prefix}/users\\\`, …)\`.`,
+                `   * change here.`,
                 `   */`,
                 `  api: {`,
                 `    prefix: "/api/v1",`,
-                `    // Where the docs/collection live, if you expose them`,
                 `    docsPath: "/api/docs",`,
                 `  },`,
                 ``,
                 `  /**`,
-                `   * HTTP behaviour consumed by the sys security module`,
-                `   * (modules/security/routes/security.routes.ts). Change the body limit`,
-                `   * or CORS origins here rather than editing that file.`,
-                `   */`,
-                `  http: {`,
-                `    // Passed to express.json({ limit }) — a parser without a cap is a`,
-                `    // memory-exhaustion invitation.`,
-                `    bodyLimit: "1mb",`,
-                `    // Browser origins allowed to call this API. Add a cors() middleware`,
-                `    // in the security module and feed it this list.`,
-                `    corsOrigins: ["http://localhost:5173"],`,
-                `    // Set true behind nginx/a load balancer so req.ip is the real client`,
-                `    // (app.set("trust proxy", config.http!.trustProxy)).`,
-                `    trustProxy: false,`,
-                `    // Seconds a request may run before you abort it, if you add a timeout`,
-                `    // middleware.`,
-                `    requestTimeout: 30,`,
-                `  },`,
-                ``,
-                `  /**`,
                 `   * List-endpoint defaults, so every module paginates identically and`,
-                `   * no caller can ask for 10 000 rows at once.`,
+                `   * no caller can ask for ten thousand rows.`,
                 `   */`,
                 `  pagination: {`,
                 `    defaultLimit: 20,`,
                 `    maxLimit: 100,`,
                 `  },`,
-                ``,
-                `  /**`,
-                `   * Cross-cutting security knobs. Secrets themselves never live here —`,
-                `   * declare them as \`"type": "secret"\` variables in meta.variables.json`,
-                `   * (redacted in logs and the banner) and read them where needed.`,
-                `   */`,
-                `  security: {`,
-                `    // Token lifetimes for an auth module, in seconds`,
-                `    accessTokenTtl: 900,        // 15 minutes`,
-                `    refreshTokenTtl: 2_592_000, // 30 days`,
-                `    // bcrypt/argon cost factor`,
-                `    passwordRounds: 12,`,
-                `    // Rate limiting, if you mount a limiter in the security module`,
-                `    rateLimit: { windowSeconds: 60, max: 100 },`,
-                `  },`,
-                ``,
-                `  /**`,
-                `   * Public-facing URLs. Anything that builds a link a human will click —`,
-                `   * password-reset emails, webhook callbacks, OAuth redirects — reads`,
-                `   * these instead of guessing the host from a request.`,
-                `   */`,
-                `  urls: {`,
-                `    // Built from PUBLIC_DOMAIN so links generated in production —`,
-                `    // reset emails, webhook callbacks — point at the real host`,
-                `    // instead of a localhost URL that is broken everywhere but this`,
-                `    // machine. The "localhost" sentinel separates the two cases.`,
-                `    api:`,
-                `      Environment.get("PUBLIC_DOMAIN") === "localhost"`,
-                `        ? \`http://localhost:\${Environment.get("PORT")}\``,
-                `        : \`https://\${Environment.get("PUBLIC_DOMAIN")}\`,`,
-                `    frontend: "http://localhost:5173",`,
-                `  },`,
-                ``,
-                `  /**`,
-                `   * Upload constraints shared by every module that accepts files.`,
-                `   */`,
-                `  uploads: {`,
-                `    maxSizeMb: 10,`,
-                `    allowedMimeTypes: ["image/png", "image/jpeg", "application/pdf"],`,
-                `  },`,
-                ``,
-                `  /**`,
-                `   * Feature flags. Cheap way to ship dark code: a module checks`,
-                `   * \`config.features!.signup\` before mounting a route. Flip per`,
-                `   * environment by reading a declared boolean variable instead of a`,
-                `   * literal.`,
-                `   */`,
-                `  features: {`,
-                `    signup: true,`,
-                `    maintenanceMode: false,`,
-                `  },`,
-                ``,
-                `  /**`,
-                `   * Localization defaults for modules that render text (emails, errors).`,
-                `   */`,
-                `  i18n: {`,
-                `    defaultLocale: "en",`,
-                `    supportedLocales: ["en", "fr"],`,
-                `  },`,
                 `})) satisfies AppConfigFn;`,
                 ``,
                 `export default appConfig;`,
                 ``,
                 `/**`,
-                ` * Types the keys above at every call site: \`ctx.config.api?.prefix\` is a`,
-                ` * string, not \`unknown\`. \`tulipes sync\` does this automatically for`,
+                ` * Types these keys at every call site: \`config.api!.prefix\` is a`,
+                ` * string, not \`unknown\`. \`yarn sync\` does this automatically for`,
                 ` * module.config.ts factories; the app-level seed types itself here.`,
-                ` * Optional (Partial) because the config object is empty until this`,
-                ` * factory has run.`,
+                ` * Partial because the config object is empty until this factory runs.`,
                 ` */`,
                 `declare module "@tulipes/core/config" {`,
                 `  interface GlobalConfig extends Partial<ReturnType<typeof appConfig>> {}`,
@@ -568,7 +469,7 @@ function renderProject(name, coreVersion) {
                 `        root /var/www/html;`,
                 `    }`,
                 ``,
-                `    # Keep in step with config.app.ts http.bodyLimit. If nginx is stricter,`,
+                `    # Keep in step with the BODY_LIMIT variable. If nginx is stricter,`,
                 `    # oversized requests die here as an nginx HTML page instead of the`,
                 `    # API's JSON 413.`,
                 `    client_max_body_size 1m;`,
@@ -590,8 +491,8 @@ function renderProject(name, coreVersion) {
                 `        proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;`,
                 `        proxy_set_header X-Forwarded-Proto $scheme;`,
                 ``,
-                `        # Set config.http.trustProxy to true so the app reads the real`,
-                `        # client IP from the headers above.`,
+                `        # app.set("trust proxy", true) in the security module lets the`,
+                `        # app read the real client IP from the headers above.`,
                 ``,
                 `        # Long-lived websockets must outlive nginx's 60s default.`,
                 `        proxy_read_timeout 3600s;`,
@@ -806,7 +707,14 @@ function renderProject(name, coreVersion) {
                 // module needs live here rather than in a top-level lib/.
                 exports: { ".": "./index.ts" },
                 tulipes: { tier: "sys", priority: 0 },
-                dependencies: { "@tulipes/core": core, ioredis: "^5", mongoose: "^8" },
+                dependencies: {
+                    "@tulipes/core": core,
+                    ioredis: "^5",
+                    mongoose: "^8",
+                    pino: "^9",
+                    "pino-pretty": "^13",
+                    "pino-roll": "^3",
+                },
             })],
         ["modules/core/meta.variables.json", json({
                 variables: [
@@ -840,6 +748,70 @@ function renderProject(name, coreVersion) {
                         description: 'Public hostname this API is served from; "localhost" means not deployed',
                         default: "localhost",
                     },
+                    {
+                        name: "LOG_LEVEL",
+                        type: "enum",
+                        enum: ["fatal", "error", "warn", "info", "debug", "trace"],
+                        group: "logging",
+                        description: "Lowest level that reaches any destination",
+                        default: "info",
+                    },
+                    {
+                        name: "LOG_CONSOLE",
+                        type: "boolean",
+                        group: "logging",
+                        description: "Pretty coloured logs on stdout; turn off where a collector reads files only",
+                        default: true,
+                    },
+                    {
+                        name: "LOG_FILE",
+                        type: "boolean",
+                        group: "logging",
+                        description: "Write JSON-line log files under LOG_DIR",
+                        default: true,
+                    },
+                    {
+                        name: "LOG_DIR",
+                        type: "string",
+                        group: "logging",
+                        description: "Directory for log files, relative to the app root or absolute",
+                        default: "logs",
+                    },
+                    {
+                        name: "LOG_BASENAME",
+                        type: "string",
+                        group: "logging",
+                        description: "Base name of the all-levels log file; the process mode and date are appended",
+                        default: "app",
+                    },
+                    {
+                        name: "LOG_ERROR_BASENAME",
+                        type: "string",
+                        group: "logging",
+                        description: "Base name of the errors-only log file; the process mode and date are appended",
+                        default: "error",
+                    },
+                    {
+                        name: "LOG_ROTATION_FREQUENCY",
+                        type: "string",
+                        group: "logging",
+                        description: 'Rotate on this schedule: "daily", "hourly", or milliseconds',
+                        default: "daily",
+                    },
+                    {
+                        name: "LOG_ROTATION_SIZE",
+                        type: "string",
+                        group: "logging",
+                        description: 'Also rotate once a file reaches this size, e.g. "20m"',
+                        default: "20m",
+                    },
+                    {
+                        name: "LOG_RETENTION_FILES",
+                        type: "number",
+                        group: "logging",
+                        description: "How many rotated files to keep per destination, besides the current one",
+                        default: 14,
+                    },
                 ],
             })],
         ["modules/core/helpers/cache/types.ts", [
@@ -1281,6 +1253,106 @@ function renderProject(name, coreVersion) {
                 `};`,
                 ``,
             ].join("\n")],
+        ["modules/core/helpers/logger/index.ts", [
+                `import { join } from "node:path";`,
+                `// Default import, not the named one: pino.transport lives on the`,
+                `// namespace that only the default export carries.`,
+                `import pino from "pino";`,
+                `import type { Logger, TransportTargetOptions } from "pino";`,
+                `import type { ProcessMode } from "@tulipes/core/boot";`,
+                `import type { Environment } from "@tulipes/core/env";`,
+                ``,
+                `/**`,
+                ` * The app's logger, shared by every module.`,
+                ` *`,
+                ` * Two destinations at once, because they answer different questions:`,
+                ` *`,
+                ` *   console  pretty and coloured, for a human watching a terminal`,
+                ` *   files    JSON lines, for grep/jq/Loki/CloudWatch — one object per`,
+                ` *            line with a stable shape, which is what makes logs queryable`,
+                ` *`,
+                ` * Files are named per process mode. Backend and worker run at the same`,
+                ` * time, and two processes rotating one file race: both notice the size`,
+                ` * limit, both rename, and one of them loses entries. Separate files cost`,
+                ` * nothing and remove the failure entirely.`,
+                ` */`,
+                `let instance: Logger | undefined;`,
+                ``,
+                `export function logger(environment: Environment, mode: ProcessMode = "backend"): Logger {`,
+                `  if (instance) return instance;`,
+                ``,
+                `  const level = String(environment.get("LOG_LEVEL"));`,
+                `  const targets: TransportTargetOptions[] = [];`,
+                ``,
+                `  if (Boolean(environment.get("LOG_CONSOLE"))) {`,
+                `    targets.push({`,
+                `      target: "pino-pretty",`,
+                `      level,`,
+                `      options: {`,
+                `        colorize: true,`,
+                `        translateTime: "SYS:HH:MM:ss.l",`,
+                `        // pid and hostname matter in aggregated files, not on the terminal`,
+                `        // of the machine that is obviously running it.`,
+                `        ignore: "pid,hostname",`,
+                `        messageFormat: "{if module}[{module}] {end}{msg}",`,
+                `      },`,
+                `    });`,
+                `  }`,
+                ``,
+                `  if (Boolean(environment.get("LOG_FILE"))) {`,
+                `    const dir = String(environment.get("LOG_DIR"));`,
+                `    const rotation = {`,
+                `      // Both limits apply: whichever trips first rotates the file.`,
+                `      frequency: String(environment.get("LOG_ROTATION_FREQUENCY")),`,
+                `      size: String(environment.get("LOG_ROTATION_SIZE")),`,
+                `      limit: { count: Number(environment.get("LOG_RETENTION_FILES")) },`,
+                `      extension: ".log",`,
+                `      dateFormat: "yyyy-MM-dd",`,
+                `      mkdir: true,`,
+                `    };`,
+                ``,
+                `    targets.push({`,
+                `      target: "pino-roll",`,
+                `      level,`,
+                `      options: { ...rotation, file: join(dir, \`\${environment.get("LOG_BASENAME")}-\${mode}\`) },`,
+                `    });`,
+                ``,
+                `    // A second copy of errors only. Everything here is also in the main`,
+                `    // file; the point is a small file to open first when something breaks,`,
+                `    // instead of paging through a day of request logs.`,
+                `    targets.push({`,
+                `      target: "pino-roll",`,
+                `      level: "error",`,
+                `      options: {`,
+                `        ...rotation,`,
+                `        file: join(dir, \`\${environment.get("LOG_ERROR_BASENAME")}-\${mode}\`),`,
+                `      },`,
+                `    });`,
+                `  }`,
+                ``,
+                `  instance = targets.length`,
+                `    ? pino({ level, base: { mode } }, pino.transport({ targets }))`,
+                `    : // Every destination disabled: still return a working logger rather`,
+                `      // than null-checking at a hundred call sites.`,
+                `      pino({ level, base: { mode } });`,
+                ``,
+                `  return instance;`,
+                `}`,
+                ``,
+                `/**`,
+                ` * A logger tagged with the module it belongs to, so a line's origin is`,
+                ` * visible in both destinations: \`[users] ready\` on the console, and a`,
+                ` * queryable \`"module":"users"\` field in the file.`,
+                ` */`,
+                `export function moduleLogger(`,
+                `  environment: Environment,`,
+                `  name: string,`,
+                `  mode: ProcessMode = "backend",`,
+                `): Logger {`,
+                `  return logger(environment, mode).child({ module: name });`,
+                `}`,
+                ``,
+            ].join("\n")],
         ["modules/core/index.ts", [
                 `/**`,
                 ` * What the core module offers the rest of the app.`,
@@ -1300,6 +1372,8 @@ function renderProject(name, coreVersion) {
                 `  type Cache,`,
                 `} from "./helpers/cache/index.js";`,
                 ``,
+                `export { logger, moduleLogger } from "./helpers/logger/index.js";`,
+                ``,
                 `export {`,
                 `  baseSchemaOptions,`,
                 `  baseModelPlugin,`,
@@ -1377,27 +1451,26 @@ function renderProject(name, coreVersion) {
                 version: "0.0.0",
                 private: true,
                 type: "module",
-                tulipes: { tier: "sys", priority: 10 },
+                // dependsOn "core" for the shared logger it imports from @app/core.
+                tulipes: { tier: "sys", priority: 10, dependsOn: ["core"] },
                 dependencies: {
                     "@tulipes/core": core,
+                    "@app/core": "workspace:*",
                     cors: "^2",
                     express: "^5",
                     helmet: "^8",
-                    pino: "^9",
                     "pino-http": "^10",
-                    "pino-pretty": "^13",
                 },
                 devDependencies: { "@types/cors": "^2" },
             })],
         ["modules/security/meta.variables.json", json({
                 variables: [
                     {
-                        name: "LOG_LEVEL",
-                        type: "enum",
-                        enum: ["fatal", "error", "warn", "info", "debug", "trace"],
-                        group: "logging",
-                        description: "Minimum pino log level",
-                        default: "info",
+                        name: "BODY_LIMIT",
+                        type: "string",
+                        group: "http",
+                        description: 'Largest JSON request body express will parse, e.g. "1mb"; nginx client_max_body_size must be at least this',
+                        default: "1mb",
                     },
                     {
                         name: "CORS_ORIGINS",
@@ -1479,33 +1552,6 @@ function renderProject(name, coreVersion) {
                 `}`,
                 ``,
             ].join("\n")],
-        ["modules/security/helpers/logger.ts", [
-                `import { pino, type Logger } from "pino";`,
-                `import type { Environment } from "@tulipes/core/env";`,
-                ``,
-                `let instance: Logger | undefined;`,
-                ``,
-                `/**`,
-                ` * The app's pino logger — JSON lines in production, pretty-printed in`,
-                ` * development. Level comes from LOG_LEVEL so a deploy can turn on`,
-                ` * debug without a code change.`,
-                ` */`,
-                `export function logger(environment: Environment): Logger {`,
-                `  if (instance) return instance;`,
-                ``,
-                `  instance = pino({`,
-                `    level: String(environment.get("LOG_LEVEL")),`,
-                `    ...(environment.appEnv === "development" && {`,
-                `      transport: {`,
-                `        target: "pino-pretty",`,
-                `        options: { translateTime: "HH:MM:ss", ignore: "pid,hostname" },`,
-                `      },`,
-                `    }),`,
-                `  });`,
-                `  return instance;`,
-                `}`,
-                ``,
-            ].join("\n")],
         ["modules/security/routes/security.routes.ts", [
                 `import cors from "cors";`,
                 `import express from "express";`,
@@ -1514,12 +1560,12 @@ function renderProject(name, coreVersion) {
                 `import type { Ctx } from "@tulipes/core/boot";`,
                 ``,
                 `import { corsOptions, helmetOptions } from "../helpers/hardening.js";`,
-                `import { logger } from "../helpers/logger.js";`,
+                `import { logger } from "@app/core";`,
                 ``,
                 `/**`,
                 ` * The app's request-hardening stack. Sys tier, so this mounts ahead of`,
-                ` * every app-tier router — the framework core mounts no middleware of`,
-                ` * its own; this module IS the pipeline's head.`,
+                ` * every app-tier router — the framework core mounts no middleware of its`,
+                ` * own; this module IS the pipeline's head.`,
                 ` *`,
                 ` * Order matters:`,
                 ` *   helmet  — headers on every response, including errors and preflights`,
@@ -1527,15 +1573,21 @@ function renderProject(name, coreVersion) {
                 ` *   pino    — logs the request once the two above have had their say`,
                 ` *   json    — parsing last, so a rejected origin never reaches the parser`,
                 ` */`,
-                `export default function securityRoutes({ app, Environment, config }: Ctx): void {`,
+                `export default function securityRoutes(ctx: Ctx): void {`,
+                `  const { app, Environment, config, mode } = ctx`,
+                ``,
                 `  app!.use(helmet(helmetOptions(Environment)));`,
                 `  app!.use(cors(corsOptions(Environment)));`,
                 ``,
                 `  app!.use(`,
                 `    pinoHttp({`,
-                `      logger: logger(Environment),`,
-                `      // The core module (priority 0) stamps X-Request-Id before this`,
-                `      // runs — reuse it so logs and response headers tell one story.`,
+                `      logger: logger(Environment, mode),`,
+                `      // Without this a 500 is logged at info, so the errors-only log file`,
+                `      // stays empty exactly when you need it.`,
+                `      customLogLevel: (_req, res, err) =>`,
+                `        err || res.statusCode >= 500 ? "error" : res.statusCode >= 400 ? "warn" : "info",`,
+                `      // The core module (priority 0) stamps X-Request-Id before this runs —`,
+                `      // reuse it so log lines and response headers tell one story.`,
                 `      genReqId: (_req, res) => String(res.getHeader("X-Request-Id") ?? ""),`,
                 `      serializers: {`,
                 `        req: (req: { method: string; url: string }) => ({`,
@@ -1547,9 +1599,11 @@ function renderProject(name, coreVersion) {
                 `    }),`,
                 `  );`,
                 ``,
-                `  // Body-size cap is a security control too — a parser without a limit`,
-                `  // is a memory-exhaustion invitation. Tuned from config/app.config.ts.`,
-                `  app!.use(express.json({ limit: config.http?.bodyLimit ?? "1mb" }));`,
+                `  // Body-size cap is a security control too — a parser without a limit is`,
+                `  // a memory-exhaustion invitation. Declared by this module, because it`,
+                `  // varies per deployment: an upload-heavy API raises it without touching`,
+                `  // code.`,
+                `  app!.use(express.json({ limit: String(Environment.get("BODY_LIMIT")) }));`,
                 `}`,
                 ``,
             ].join("\n")],
@@ -1781,6 +1835,8 @@ function renderProject(name, coreVersion) {
             `import type { Ctx } from "@tulipes/core/boot";`,
             `import type { QueueRegistry } from "@tulipes/core/queues";`,
             ``,
+            `import { moduleLogger } from "@app/core";`,
+            ``,
             `/**`,
             ` * ONE file describes both sides. The backend process registers the queue`,
             ` * so routes can produce into it; \`yarn worker\` turns the processor`,
@@ -1788,7 +1844,12 @@ function renderProject(name, coreVersion) {
             ` *`,
             ` * Queue names use "." — BullMQ reserves ":" as its redis separator.`,
             ` */`,
-            `export default function helloQueues({ models }: Ctx, queues: QueueRegistry): void {`,
+            `export default function helloQueues(ctx: Ctx, queues: QueueRegistry): void {`,
+            `  const { models } = ctx;`,
+            `  // The same logger the backend uses. In the worker process it writes`,
+            `  // to app-worker.log, so the two processes never share a file.`,
+            `  const log = moduleLogger(ctx.Environment, "hello", ctx.mode);`,
+            ``,
             `  queues.define("hello.count-greeting");`,
             ``,
             `  queues.process("hello.count-greeting", async (job) => {`,
@@ -1796,6 +1857,7 @@ function renderProject(name, coreVersion) {
             `    // job.data and re-read state here rather than shipping documents.`,
             `    const { name } = job.data as { name: string };`,
             `    await models!.get("Greeting").updateOne({ name }, { $inc: { timesUsed: 1 } });`,
+            `    log.info({ name }, "counted greeting");`,
             `    return { counted: name };`,
             `  });`,
             `}`,
@@ -1891,6 +1953,35 @@ function renderProject(name, coreVersion) {
             `| \`yarn tulipes new module <name>\` | scaffold a module |`,
             `| \`yarn tulipes update\` | upgrade the framework everywhere it is declared |`,
             ``,
+            `## 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.`,
+            ``,
+            `Everything is configured from \`modules/core/meta.variables.json\`:`,
+            `\`LOG_LEVEL\`, \`LOG_CONSOLE\`, \`LOG_FILE\`, \`LOG_DIR\`, \`LOG_BASENAME\`,`,
+            `\`LOG_ERROR_BASENAME\`, and rotation via \`LOG_ROTATION_FREQUENCY\`,`,
+            `\`LOG_ROTATION_SIZE\` and \`LOG_RETENTION_FILES\` (how many rotated files`,
+            `to keep). Rotation happens on whichever of frequency or size trips`,
+            `first.`,
+            ``,
             `## Scripts`,
             ``,
             `\`scripts/\` holds one-off tasks — backfills, exports, admin chores.`,