@tulipes/core 0.1.9 → 0.1.11

package/dist/cli/init.js

@@ -303,9 +303,6 @@ function renderProject(name, coreVersion) {
                 `   * 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"],`,
@@ -568,7 +565,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;`,
@@ -802,8 +799,18 @@ function renderProject(name, coreVersion) {
                 version: "0.0.0",
                 private: true,
                 type: "module",
+                // Importable by other modules as "@app/core": helpers more than one
+                // module needs live here rather than in a top-level lib/.
+                exports: { ".": "./index.ts" },
                 tulipes: { tier: "sys", priority: 0 },
-                dependencies: { "@tulipes/core": core },
+                dependencies: {
+                    "@tulipes/core": core,
+                    ioredis: "^5",
+                    mongoose: "^8",
+                    pino: "^9",
+                    "pino-pretty": "^13",
+                    "pino-roll": "^3",
+                },
             })],
         ["modules/core/meta.variables.json", json({
                 variables: [
@@ -837,8 +844,671 @@ 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", [
+                `/**`,
+                ` * Storage-agnostic cache contract. Implementations serialize values`,
+                ` * themselves; callers work with plain objects. Keep it small — add methods`,
+                ` * only when a real use case needs them.`,
+                ` */`,
+                `export interface Cache {`,
+                `  /** Returns the cached value, or \`null\` if absent/expired. */`,
+                `  get<T>(key: string): Promise<T | null>;`,
+                `  /** Stores a value, optionally expiring after \`ttlSeconds\`. */`,
+                `  set<T>(key: string, value: T, ttlSeconds?: number): Promise<void>;`,
+                `  /** Removes a key (no-op if absent). */`,
+                `  del(key: string): Promise<void>;`,
+                `  /**`,
+                `   * Returns the cached value, or computes it with \`producer\`, caches it for`,
+                `   * \`ttlSeconds\`, and returns it (read-through).`,
+                `   */`,
+                `  wrap<T>(key: string, ttlSeconds: number, producer: () => Promise<T>): Promise<T>;`,
+                `}`,
+                ``,
+                `/**`,
+                ` * Shared read-through logic so drivers only implement storage. A driver that`,
+                ` * can do it atomically (e.g. redis with locks) is free to override.`,
+                ` */`,
+                `export abstract class BaseCache implements Cache {`,
+                `  abstract get<T>(key: string): Promise<T | null>;`,
+                `  abstract set<T>(key: string, value: T, ttlSeconds?: number): Promise<void>;`,
+                `  abstract del(key: string): Promise<void>;`,
+                ``,
+                `  async wrap<T>(key: string, ttlSeconds: number, producer: () => Promise<T>): Promise<T> {`,
+                `    const cached = await this.get<T>(key);`,
+                `    if (cached !== null) return cached;`,
+                ``,
+                `    const fresh = await producer();`,
+                `    await this.set(key, fresh, ttlSeconds);`,
+                `    return fresh;`,
+                `  }`,
+                `}`,
+                ``,
+            ].join("\n")],
+        ["modules/core/helpers/cache/memory-cache.ts", [
+                `import { BaseCache } from "./types.js";`,
+                ``,
+                `interface Entry {`,
+                `  value: unknown;`,
+                `  /** Epoch ms when this entry expires, or \`null\` for no expiry. */`,
+                `  expiresAt: number | null;`,
+                `}`,
+                ``,
+                `/**`,
+                ` * In-process cache backed by a \`Map\`. For tests and local runs without`,
+                ` * Redis — not shared across processes (each worker has its own store).`,
+                ` *`,
+                ` * Bounded: past \`maxEntries\` the least-recently-used key is evicted. LRU`,
+                ` * order rides on Map insertion order — hits re-insert their key at the tail.`,
+                ` */`,
+                `export class MemoryCache extends BaseCache {`,
+                `  readonly #store = new Map<string, Entry>();`,
+                `  readonly #maxEntries: number;`,
+                ``,
+                `  constructor(maxEntries = 10_000) {`,
+                `    super();`,
+                `    this.#maxEntries = maxEntries;`,
+                `  }`,
+                ``,
+                `  async get<T>(key: string): Promise<T | null> {`,
+                `    const entry = this.#store.get(key);`,
+                `    if (!entry) return null;`,
+                `    if (entry.expiresAt !== null && entry.expiresAt <= Date.now()) {`,
+                `      this.#store.delete(key);`,
+                `      return null;`,
+                `    }`,
+                `    // Refresh recency: delete + re-set moves the key to the Map's tail.`,
+                `    this.#store.delete(key);`,
+                `    this.#store.set(key, entry);`,
+                `    return entry.value as T;`,
+                `  }`,
+                ``,
+                `  async set<T>(key: string, value: T, ttlSeconds?: number): Promise<void> {`,
+                `    const expiresAt =`,
+                `      ttlSeconds && ttlSeconds > 0 ? Date.now() + ttlSeconds * 1000 : null;`,
+                `    this.#store.delete(key);`,
+                `    this.#store.set(key, { value, expiresAt });`,
+                ``,
+                `    while (this.#store.size > this.#maxEntries) {`,
+                `      // Oldest key = head of the Map's insertion order.`,
+                `      this.#store.delete(this.#store.keys().next().value!);`,
+                `    }`,
+                `  }`,
+                ``,
+                `  async del(key: string): Promise<void> {`,
+                `    this.#store.delete(key);`,
+                `  }`,
+                `}`,
+                ``,
+            ].join("\n")],
+        ["modules/core/helpers/cache/redis-cache.ts", [
+                `import type { Redis } from "ioredis";`,
+                `import { BaseCache } from "./types.js";`,
+                ``,
+                `/**`,
+                ` * Redis-backed cache. Values are JSON-serialized; keys are namespaced by`,
+                ` * \`prefix\` so cache keys never collide with other Redis users in the same`,
+                ` * db (BullMQ especially) and can be cleared without a FLUSHDB.`,
+                ` */`,
+                `export class RedisCache extends BaseCache {`,
+                `  readonly #redis: Redis;`,
+                `  readonly #prefix: string;`,
+                ``,
+                `  constructor(redis: Redis, prefix = "cache:") {`,
+                `    super();`,
+                `    this.#redis = redis;`,
+                `    this.#prefix = prefix;`,
+                `  }`,
+                ``,
+                `  #key(key: string): string {`,
+                `    return \`\${this.#prefix}\${key}\`;`,
+                `  }`,
+                ``,
+                `  async get<T>(key: string): Promise<T | null> {`,
+                `    const raw = await this.#redis.get(this.#key(key));`,
+                `    return raw === null ? null : (JSON.parse(raw) as T);`,
+                `  }`,
+                ``,
+                `  async set<T>(key: string, value: T, ttlSeconds?: number): Promise<void> {`,
+                `    const raw = JSON.stringify(value);`,
+                `    if (ttlSeconds && ttlSeconds > 0) {`,
+                `      await this.#redis.set(this.#key(key), raw, "EX", ttlSeconds);`,
+                `    } else {`,
+                `      await this.#redis.set(this.#key(key), raw);`,
+                `    }`,
+                `  }`,
+                ``,
+                `  async del(key: string): Promise<void> {`,
+                `    await this.#redis.del(this.#key(key));`,
+                `  }`,
+                `}`,
+                ``,
+            ].join("\n")],
+        ["modules/core/helpers/cache/index.ts", [
+                `import { Redis } from "ioredis";`,
+                `import type { Environment } from "@tulipes/core/env";`,
+                ``,
+                `import { MemoryCache } from "./memory-cache.js";`,
+                `import { RedisCache } from "./redis-cache.js";`,
+                `import type { Cache } from "./types.js";`,
+                ``,
+                `export type { Cache } from "./types.js";`,
+                `export { BaseCache } from "./types.js";`,
+                `export { MemoryCache } from "./memory-cache.js";`,
+                `export { RedisCache } from "./redis-cache.js";`,
+                ``,
+                `let active: { cache: Cache; redis?: Redis } | undefined;`,
+                ``,
+                `/**`,
+                ` * The app's one cache, picked from the environment: redis when REDIS_URL is`,
+                ` * declared, in-process memory otherwise (tests, minimal setups). Lazily`,
+                ` * created, process-wide singleton.`,
+                ` */`,
+                `export function appCache(environment: Environment): Cache {`,
+                `  if (active) return active.cache;`,
+                ``,
+                `  if (environment.store.has("REDIS_URL")) {`,
+                `    const redis = new Redis(String(environment.get("REDIS_URL")));`,
+                `    active = { cache: new RedisCache(redis), redis };`,
+                `  } else {`,
+                `    active = { cache: new MemoryCache() };`,
+                `  }`,
+                `  return active.cache;`,
+                `}`,
+                ``,
+                `/** Call from a module's onShutdown — the redis driver holds a connection. */`,
+                `export async function closeCache(): Promise<void> {`,
+                `  await active?.redis?.quit();`,
+                `  active = undefined;`,
+                `}`,
+                ``,
+            ].join("\n")],
+        ["modules/core/helpers/mongoose/plugins/types.ts", [
+                `import type { Document, ObjectId, Types } from "mongoose";`,
+                ``,
+                `/**`,
+                ` * Who performed a soft delete — a polymorphic reference. \`model\` is the`,
+                ` * actor's Mongoose model name (e.g. "User") and \`id\` its \`_id\`; together`,
+                ` * they let \`.populate("deleted_by.id")\` resolve the actor via \`refPath\`.`,
+                ` */`,
+                `export interface Actor {`,
+                `  model: string;`,
+                `  id: Types.ObjectId;`,
+                `}`,
+                ``,
+                `/** Timestamp fields added by \`timestampsPlugin\`. */`,
+                `export interface Timestamps {`,
+                `  created_at: Date;`,
+                `  updated_at: Date;`,
+                `}`,
+                ``,
+                `/** Fields added by \`softDeletePlugin\`. */`,
+                `export interface SoftDeleteFields {`,
+                `  is_deleted: boolean;`,
+                `  deleted_at: Date | null;`,
+                `  deleted_by: Actor | null;`,
+                `}`,
+                ``,
+                `/** Instance methods added by \`softDeletePlugin\`. */`,
+                `export interface SoftDeleteMethods {`,
+                `  /** Flag this document as deleted (optionally recording the actor) and save. */`,
+                `  softDelete(by?: Actor): Promise<this>;`,
+                `  /** Clear the soft-delete flags and save. */`,
+                `  restore(): Promise<this>;`,
+                `}`,
+                ``,
+                `/**`,
+                ` * Everything the base plugin contributes to a document. Model interfaces`,
+                ` * extend this to inherit the fields and methods, typed. The \`_id\` type`,
+                ` * defaults to \`ObjectId\` but can be overridden:`,
+                ` *`,
+                ` *   export interface IUser extends BaseDocument { name: string }`,
+                ` *   export interface IApiKey extends BaseDocument<string> { name: string }`,
+                ` */`,
+                `export type BaseDocument<T = ObjectId> = Document<T> &`,
+                `  Timestamps &`,
+                `  SoftDeleteFields &`,
+                `  SoftDeleteMethods;`,
+                ``,
+            ].join("\n")],
+        ["modules/core/helpers/mongoose/plugins/timestamps.plugin.ts", [
+                `import type { Schema } from "mongoose";`,
+                ``,
+                `/**`,
+                ` * Mongoose-managed \`created_at\` / \`updated_at\` (snake_case, matching the`,
+                ` * API's wire format). Mongoose populates them on create/update — no manual`,
+                ` * defaults or hooks needed.`,
+                ` */`,
+                `export function timestampsPlugin(schema: Schema): void {`,
+                `  schema.set("timestamps", {`,
+                `    createdAt: "created_at",`,
+                `    updatedAt: "updated_at",`,
+                `  });`,
+                `}`,
+                ``,
+            ].join("\n")],
+        ["modules/core/helpers/mongoose/plugins/soft-delete.plugin.ts", [
+                `import {`,
+                `  Schema,`,
+                `  type Aggregate,`,
+                `  type HydratedDocument,`,
+                `  type Model,`,
+                `  type Query,`,
+                `} from "mongoose";`,
+                ``,
+                `import type { Actor, SoftDeleteFields } from "./types.js";`,
+                ``,
+                `/** Option carried on a query/aggregation to opt out of the soft-delete filter. */`,
+                `interface SoftDeleteOptions {`,
+                `  withDeleted?: boolean;`,
+                `}`,
+                ``,
+                `const deletedPatch = (by?: Actor) => ({`,
+                `  is_deleted: true,`,
+                `  deleted_at: new Date(),`,
+                `  deleted_by: by ?? null,`,
+                `});`,
+                ``,
+                `const restoredPatch = () => ({`,
+                `  is_deleted: false,`,
+                `  deleted_at: null,`,
+                `  deleted_by: null,`,
+                `});`,
+                ``,
+                `/**`,
+                ` * Hides soft-deleted documents from reads and updates. Skipped when the`,
+                ` * caller opted out via \`.withDeleted()\` or already targeted \`is_deleted\``,
+                ` * explicitly. Uses \`$ne: true\` (not \`=== false\`) so legacy documents`,
+                ` * missing the field are still treated as live.`,
+                ` */`,
+                `function excludeDeleted(this: Query<unknown, unknown>) {`,
+                `  const { withDeleted } = this.getOptions() as SoftDeleteOptions;`,
+                `  if (withDeleted) return;`,
+                `  if (this.getFilter().is_deleted !== undefined) return;`,
+                `  this.where({ is_deleted: { $ne: true } });`,
+                `}`,
+                ``,
+                `/** The aggregation-pipeline equivalent of {@link excludeDeleted}. */`,
+                `function excludeDeletedFromAggregate(this: Aggregate<unknown[]>) {`,
+                `  const { withDeleted } = (this.options ?? {}) as SoftDeleteOptions;`,
+                `  if (withDeleted) return;`,
+                `  this.pipeline().unshift({ $match: { is_deleted: { $ne: true } } });`,
+                `}`,
+                ``,
+                `/**`,
+                ` * The \`deleted_by\` actor as a nested sub-schema (no own \`_id\`) so the whole`,
+                ` * object can be \`null\` while the document is live. \`refPath\` makes \`id\` a`,
+                ` * polymorphic reference resolved against the model named in`,
+                ` * \`deleted_by.model\`.`,
+                ` */`,
+                `const deletedBySchema = new Schema<Actor>(`,
+                `  {`,
+                `    model: { type: String, required: true },`,
+                `    id: { type: Schema.Types.ObjectId, required: true, refPath: "deleted_by.model" },`,
+                `  },`,
+                `  { _id: false },`,
+                `);`,
+                ``,
+                `/**`,
+                ` * Soft deletion: an \`is_deleted\` flag plus \`deleted_at\` and a polymorphic`,
+                ` * \`deleted_by\` actor. Deleted documents are transparently excluded from`,
+                ` * queries unless explicitly included.`,
+                ` *`,
+                ` *   read incl. deleted:   Model.find().withDeleted()   (or setOptions)`,
+                ` *   read only deleted:    Model.find().onlyDeleted()`,
+                ` *   delete one:           await doc.softDelete(actor)`,
+                ` *   delete many:          await Model.softDelete(filter, actor)`,
+                ` *   restore:              await doc.restore() / await Model.restore(filter)`,
+                ` */`,
+                `export function softDeletePlugin(schema: Schema): void {`,
+                `  schema.add({`,
+                `    is_deleted: { type: Boolean, default: false, index: true },`,
+                `    deleted_at: { type: Date, default: null },`,
+                `    deleted_by: { type: deletedBySchema, default: null },`,
+                `  });`,
+                ``,
+                `  // Covers find*, count*, distinct, update*, replace*. Hard deletes`,
+                `  // (deleteOne/deleteMany) stay literal on purpose — when code says`,
+                `  // delete, the framework must not silently downgrade it.`,
+                `  schema.pre(/^(count|find|distinct|update|replace)/, excludeDeleted);`,
+                `  schema.pre("aggregate", excludeDeletedFromAggregate);`,
+                ``,
+                `  const query = schema.query as Record<string, (...args: never[]) => unknown>;`,
+                `  query.withDeleted = function (this: Query<unknown, unknown>) {`,
+                `    return this.setOptions({ withDeleted: true } as SoftDeleteOptions);`,
+                `  };`,
+                `  query.onlyDeleted = function (this: Query<unknown, unknown>) {`,
+                `    return this.setOptions({ withDeleted: true } as SoftDeleteOptions).where({`,
+                `      is_deleted: true,`,
+                `    });`,
+                `  };`,
+                ``,
+                `  schema.methods.softDelete = function (`,
+                `    this: HydratedDocument<SoftDeleteFields>,`,
+                `    by?: Actor,`,
+                `  ) {`,
+                `    this.set(deletedPatch(by));`,
+                `    return this.save();`,
+                `  };`,
+                `  schema.methods.restore = function (this: HydratedDocument<SoftDeleteFields>) {`,
+                `    this.set(restoredPatch());`,
+                `    return this.save();`,
+                `  };`,
+                ``,
+                `  schema.statics.softDelete = function (`,
+                `    this: Model<unknown>,`,
+                `    filter: Record<string, unknown>,`,
+                `    by?: Actor,`,
+                `  ) {`,
+                `    return this.updateMany(filter, { $set: deletedPatch(by) });`,
+                `  };`,
+                `  schema.statics.restore = function (`,
+                `    this: Model<unknown>,`,
+                `    filter: Record<string, unknown>,`,
+                `  ) {`,
+                `    // withDeleted so the guard doesn't filter out the very docs we restore.`,
+                `    return this.updateMany(filter, { $set: restoredPatch() }).setOptions({`,
+                `      withDeleted: true,`,
+                `    } as SoftDeleteOptions);`,
+                `  };`,
+                `}`,
+                ``,
+            ].join("\n")],
+        ["modules/core/helpers/mongoose/plugins/base.plugin.ts", [
+                `import type { Schema } from "mongoose";`,
+                ``,
+                `import { softDeletePlugin } from "./soft-delete.plugin.js";`,
+                `import { timestampsPlugin } from "./timestamps.plugin.js";`,
+                ``,
+                `/**`,
+                ` * The base plugin every model gets. Composes the focused plugins so each`,
+                ` * stays single-responsibility; new cross-cutting behaviour (audit trail,`,
+                ` * versioning, …) slots in here without touching call sites.`,
+                ` */`,
+                `export function baseModelPlugin(schema: Schema): void {`,
+                `  schema.plugin(timestampsPlugin);`,
+                `  schema.plugin(softDeletePlugin);`,
+                `}`,
+                ``,
+            ].join("\n")],
+        ["modules/core/helpers/mongoose/register.ts", [
+                `import mongoose from "mongoose";`,
+                ``,
+                `import { baseModelPlugin } from "./plugins/base.plugin.js";`,
+                ``,
+                `let registered = false;`,
+                ``,
+                `/**`,
+                ` * Registers the base plugin globally so EVERY schema gets timestamps + soft`,
+                ` * delete. Global plugins only affect models compiled after registration, so`,
+                ` * call this before boot() — it's the first line of app.ts and worker.ts.`,
+                ` *`,
+                ` * An explicit function, deliberately not an import side effect: the old`,
+                ` * framework's side-effect register module made correctness depend on import`,
+                ` * order, which is exactly the class of bug this framework exists to kill.`,
+                ` */`,
+                `export function registerBasePlugins(): void {`,
+                `  if (registered) return;`,
+                `  registered = true;`,
+                `  mongoose.plugin(baseModelPlugin);`,
+                `}`,
+                ``,
+            ].join("\n")],
+        ["modules/core/helpers/mongoose/index.ts", [
+                `import type { SchemaOptions } from "mongoose";`,
+                ``,
+                `export { baseModelPlugin } from "./plugins/base.plugin.js";`,
+                `export { softDeletePlugin } from "./plugins/soft-delete.plugin.js";`,
+                `export { timestampsPlugin } from "./plugins/timestamps.plugin.js";`,
+                `export { registerBasePlugins } from "./register.js";`,
+                `export type {`,
+                `  Actor,`,
+                `  BaseDocument,`,
+                `  SoftDeleteFields,`,
+                `  SoftDeleteMethods,`,
+                `  Timestamps,`,
+                `} from "./plugins/types.js";`,
+                ``,
+                `/**`,
+                ` * Serialization conventions every model spreads into its schema options.`,
+                ` * Timestamps are NOT set here — the base plugin owns them (snake_case).`,
+                ` */`,
+                `export const baseSchemaOptions: SchemaOptions = {`,
+                `  toJSON: {`,
+                `    versionKey: false,`,
+                `    transform: (_doc, ret: Record<string, unknown>) => {`,
+                `      delete ret._id;`,
+                `      return ret;`,
+                `    },`,
+                `  },`,
+                `};`,
+                ``,
+            ].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.`,
+                ` *`,
+                ` * Other modules import these by package name — \`@app/core\` — never by a`,
+                ` * relative path climbing out of their own folder. That is what keeps the`,
+                ` * dependency visible: a module that uses this has to declare @app/core,`,
+                ` * so the coupling shows up in its package.json instead of hiding in an`,
+                ` * import string.`,
+                ` */`,
+                `export {`,
+                `  appCache,`,
+                `  closeCache,`,
+                `  BaseCache,`,
+                `  MemoryCache,`,
+                `  RedisCache,`,
+                `  type Cache,`,
+                `} from "./helpers/cache/index.js";`,
+                ``,
+                `export { logger, moduleLogger } from "./helpers/logger/index.js";`,
+                ``,
+                `export {`,
+                `  baseSchemaOptions,`,
+                `  baseModelPlugin,`,
+                `  softDeletePlugin,`,
+                `  timestampsPlugin,`,
+                `  registerBasePlugins,`,
+                `  type Actor,`,
+                `  type BaseDocument,`,
+                `  type SoftDeleteFields,`,
+                `  type SoftDeleteMethods,`,
+                `  type Timestamps,`,
+                `} from "./helpers/mongoose/index.js";`,
+                ``,
+            ].join("\n")],
+        ["modules/core/module.config.ts", [
+                `import type { Ctx } from "@tulipes/core/boot";`,
+                ``,
+                `import { closeCache } from "./helpers/cache/index.js";`,
+                `import { registerBasePlugins } from "./helpers/mongoose/index.js";`,
+                ``,
+                `/**`,
+                ` * Registering here — phase 6, before models compile in phase 8 — is`,
+                ` * what makes the base plugins apply in EVERY mode: backend, worker`,
+                ` * and script alike. Doing it in app.ts instead would leave scripts`,
+                ` * compiling models without timestamps or the soft-delete guard, so a`,
+                ` * script would happily return rows the API considers deleted.`,
+                ` */`,
+                `registerBasePlugins();`,
+                ``,
+                `export default function coreConfig(_ctx: Ctx) {`,
+                `  return {};`,
+                `}`,
+                ``,
+                `/** The sys core module owns app-wide infra glue lifecycles. */`,
+                `export async function onShutdown(): Promise<void> {`,
+                `  await closeCache();`,
+                `}`,
+                ``,
+            ].join("\n")],
         ["modules/core/module.acl.ts", [
                 `import type { AclBuilder } from "@tulipes/core/acl";`,
                 ``,
@@ -877,27 +1547,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",
@@ -979,33 +1648,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";`,
@@ -1014,12 +1656,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`,
@@ -1027,15 +1669,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 }) => ({`,
@@ -1047,9 +1695,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")],
@@ -1058,9 +1708,10 @@ function renderProject(name, coreVersion) {
                 version: "0.0.0",
                 private: true,
                 type: "module",
-                tulipes: { tier: "app", priority: 100, dependsOn: [] },
+                tulipes: { tier: "app", priority: 100, dependsOn: ["core"] },
                 dependencies: {
                     "@tulipes/core": core,
+                    "@app/core": "workspace:*",
                     express: "^5",
                     mongoose: "^8",
                 },
@@ -1226,6 +1877,10 @@ function renderProject(name, coreVersion) {
             `import { Schema } from "mongoose";`,
             `import type { ModelDef } from "@tulipes/core/db";`,
             ``,
+            `// Cross-module import by package name, never a relative path out`,
+            `// of the module — the dependency is declared in package.json.`,
+            `import { baseSchemaOptions } from "@app/core";`,
+            ``,
             `/**`,
             ` * A model file is a DECLARATION, never a registration: the framework`,
             ` * compiles the schema on its own connection and puts it in the model`,
@@ -1239,7 +1894,7 @@ function renderProject(name, coreVersion) {
             `    message: { type: String, required: true },`,
             `    timesUsed: { type: Number, default: 0, min: 0 },`,
             `  },`,
-            `  { timestamps: true },`,
+            `  baseSchemaOptions,`,
             `);`,
             ``,
             `export default { name: "Greeting", schema: greetingSchema } satisfies ModelDef;`,
@@ -1257,17 +1912,27 @@ function renderProject(name, coreVersion) {
             `export default async function seedGreetings({ models }: Ctx): Promise<void> {`,
             `  const Greeting = models!.get("Greeting");`,
             ``,
-            `  await Greeting.updateOne(`,
-            `    { name: "world" },`,
-            `    { $setOnInsert: { name: "world", message: "Hello, world!" } },`,
-            `    { upsert: true },`,
-            `  );`,
+            `  try {`,
+            `    await Greeting.updateOne(`,
+            `      { name: "world" },`,
+            `      { $setOnInsert: { name: "world", message: "Hello, world!" } },`,
+            `      { upsert: true },`,
+            `    );`,
+            `  } catch (error) {`,
+            `    // Bootstrap tasks run in EVERY process, and backend and worker`,
+            `    // start together — concurrent upserts on a unique index race by`,
+            `    // design, and the loser gets a duplicate-key error. The row`,
+            `    // exists either way, which is all this task wanted.`,
+            `    if ((error as { code?: number }).code !== 11000) throw error;`,
+            `  }`,
             `}`,
             ``,
         ].join("\n")], ["modules/hello/queues/hello.queues.ts", [
             `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`,
@@ -1275,7 +1940,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) => {`,
@@ -1283,6 +1953,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 };`,
             `  });`,
             `}`,
@@ -1378,6 +2049,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.`,