@tulipes/core 0.1.2 → 0.1.4

package/dist/cli/init.js

@@ -1,33 +1,40 @@
-import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
+import { cpSync, existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
 import { basename, dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 /**
- * `tulipes init [dir]` — scaffold a complete application that boots with
- * ZERO infrastructure: the generated core module declares no MONGO_URI or
- * REDIS_URL, and with no models and no queue files the pipeline skips both
- * engines legitimately. `yarn install && yarn dev` must always succeed on a
- * bare machine; databases arrive later as one meta.variables.json entry.
+ * `tulipes init [dir] [--full]` — scaffold a complete application.
  *
  * Three modules ship: core (sys 0 — env contract, roles, request ids),
- * security (sys 10 — headers, pino logging, body parsing) and hello (the
- * app-tier proof route). Templates live inline, like `new module`.
+ * security (sys 10 — helmet, cors, logging, body parsing) and hello, a
+ * worked example of every module contract.
+ *
+ * By default the app boots with ZERO infrastructure: no MONGO_URI or
+ * REDIS_URL is declared, and with no models and no queue files the
+ * pipeline skips both engines legitimately, so `yarn install && yarn dev`
+ * always succeeds on a bare machine.
+ *
+ * `--full` adds the contracts that cannot work without infrastructure —
+ * models, bootstrap tasks and queues — along with the variables they
+ * require. That app needs mongo and redis running to boot.
  */
-export async function runInit(rootDir, target) {
+export async function runInit(rootDir, target, options = {}) {
     const dir = resolve(rootDir, target ?? ".");
     const name = sanitizeName(basename(dir));
+    const full = options.full ?? false;
     if (existsSync(dir) && readdirSync(dir).some((entry) => entry !== ".git")) {
         console.error(`refusing to init: ${dir} is not empty`);
         process.exitCode = 1;
         return;
     }
     const coreVersion = ownVersion();
-    const files = renderProject(name, coreVersion);
+    const files = renderProject(name, coreVersion, full);
     for (const [relPath, content] of files) {
         const filePath = join(dir, relPath);
         mkdirSync(dirname(filePath), { recursive: true });
         writeFileSync(filePath, content);
         console.log(`  create ${relPath}`);
     }
+    copyAgentGuides(dir);
     console.log([
         "",
         `Project "${name}" is ready. Next:`,
@@ -39,8 +46,9 @@ export async function runInit(rootDir, target) {
         "",
         "  → http://localhost:3000/hello",
         "",
-        "No database or redis needed to boot — add MONGO_URI / REDIS_URL to",
-        "modules/core/meta.variables.json when your first model or queue lands.",
+        full
+            ? "Needs mongo and redis running (MONGO_URI / REDIS_URL in .envs/.env.development).\nRun `yarn worker` in a second terminal to consume queued jobs."
+            : "No database or redis needed to boot — add MONGO_URI / REDIS_URL to\nmodules/core/meta.variables.json when your first model or queue lands,\nor scaffold them now with `tulipes init --full`.",
     ].filter((line) => line !== undefined).join("\n"));
 }
 /**
@@ -49,18 +57,47 @@ export async function runInit(rootDir, target) {
  * the exports map deliberately doesn't expose package.json.
  */
 function ownVersion() {
-    const pkgPath = join(dirname(fileURLToPath(import.meta.url)), "..", "..", "package.json");
-    const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+    const pkg = JSON.parse(readFileSync(join(packageRoot(), "package.json"), "utf8"));
     return pkg.version;
 }
+function packageRoot() {
+    return join(dirname(fileURLToPath(import.meta.url)), "..", "..");
+}
+/**
+ * Instructions for AI coding agents working in the generated app: an
+ * always-loaded CLAUDE.md plus task-scoped skills. They ship as real
+ * markdown in the package (templates/) rather than string literals here,
+ * so they stay editable and reviewable as documents.
+ *
+ * The source tree uses `claude/` and is written out as `.claude/`: npm
+ * has a long history of mangling dot-prefixed paths inside published
+ * tarballs, and this sidesteps it entirely.
+ */
+function copyAgentGuides(dir) {
+    const templates = join(packageRoot(), "templates");
+    if (!existsSync(templates))
+        return; // tolerate a stripped install
+    const claudeMd = join(templates, "CLAUDE.md");
+    if (existsSync(claudeMd)) {
+        cpSync(claudeMd, join(dir, "CLAUDE.md"));
+        console.log("  create CLAUDE.md");
+    }
+    const skills = join(templates, "claude");
+    if (existsSync(skills)) {
+        cpSync(skills, join(dir, ".claude"), { recursive: true });
+        for (const skill of readdirSync(join(skills, "skills"))) {
+            console.log(`  create .claude/skills/${skill}/SKILL.md`);
+        }
+    }
+}
 function sanitizeName(raw) {
     const name = raw.toLowerCase().replace(/[^a-z0-9-]+/g, "-").replace(/^-+|-+$/g, "");
     return name || "tulipes-app";
 }
 const json = (value) => JSON.stringify(value, null, 2) + "\n";
-function renderProject(name, coreVersion) {
+function renderProject(name, coreVersion, full) {
     const core = `^${coreVersion}`;
-    return [
+    const files = [
         ["package.json", json({
                 name,
                 private: true,
@@ -76,8 +113,12 @@ function renderProject(name, coreVersion) {
                     check: "tulipes env:check",
                     typecheck: "tsc --noEmit",
                 },
-                dependencies: { "@tulipes/core": core },
+                dependencies: {
+                    "@tulipes/core": core,
+                    express: "^5",
+                },
                 devDependencies: {
+                    "@types/express": "^5",
                     "@types/node": "^24",
                     tsx: "^4",
                     typescript: "^7",
@@ -98,6 +139,20 @@ function renderProject(name, coreVersion) {
                 },
                 include: ["app.ts", "worker.ts", "types", "modules", "config"],
             })],
+        [".yarnrc.yml", [
+                `nodeLinker: node-modules`,
+                ``,
+                `# tsx (esbuild) and bullmq's native helpers need their install scripts;`,
+                `# stated explicitly so a restrictive global yarn config can't break dev.`,
+                `enableScripts: true`,
+                ``,
+                `# Yarn's release-age gate quarantines freshly published packages, which`,
+                `# would block brand-new @tulipes releases from installing. Preapprove the`,
+                `# framework scope only — the gate stays active for everything else.`,
+                `npmPreapprovedPackages:`,
+                `  - "@tulipes/*"`,
+                ``,
+            ].join("\n")],
         [".gitignore", [
                 "node_modules/",
                 "dist/",
@@ -128,18 +183,156 @@ function renderProject(name, coreVersion) {
                 `import type { AppConfigFn } from "@tulipes/core/boot";`,
                 ``,
                 `/**`,
-                ` * Seeds the global config BEFORE any module factory runs. The place for`,
-                ` * app-wide values that belong to no single module.`,
+                ` * ── 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>\`:`,
+                ` *`,
+                ` *   export default function usersRoutes({ config }: Ctx) {`,
+                ` *     const router = Router();`,
+                ` *     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.`,
+                ` *`,
+                ` * 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.`,
                 ` */`,
-                `const appConfig: AppConfigFn = (Environment) => ({`,
+                `// \`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.`,
+                `   */`,
                 `  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`,
+                `   * hardcoding "/api/v1", so versioning the whole API is a one-line`,
+                `   * change here: \`router.get(\\\`\${config.api!.prefix}/users\\\`, …)\`.`,
+                `   */`,
+                `  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.`,
+                `   */`,
+                `  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: {`,
+                `    api: \`http://localhost:\${Environment.get("PORT")}\`,`,
+                `    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`,
+                ` * module.config.ts factories; the app-level seed types itself here.`,
+                ` * Optional (Partial) because the config object is empty until this`,
+                ` * factory has run.`,
+                ` */`,
+                `declare module "@tulipes/core/config" {`,
+                `  interface GlobalConfig extends Partial<ReturnType<typeof appConfig>> {}`,
+                `}`,
+                ``,
             ].join("\n")],
         [".envs/.env.development", [
                 `# Development mode — committed on purpose; values here are dev defaults.`,
@@ -149,6 +342,17 @@ function renderProject(name, coreVersion) {
                 `PORT=3000`,
                 `LOG_LEVEL=debug`,
                 ``,
+                `# Browser origins allowed to call this API. Empty (the default) allows`,
+                `# none; "*" allows any but forbids credentials.`,
+                `CORS_ORIGINS=http://localhost:5173`,
+                ``,
+                ...(full
+                    ? [
+                        `MONGO_URI=mongodb://127.0.0.1:27017/${name}`,
+                        `REDIS_URL=redis://127.0.0.1:6379`,
+                        ``,
+                    ]
+                    : []),
             ].join("\n")],
         // ── modules/core — sys tier, priority 0: the very first router ─────────
         ["modules/core/package.json", json({
@@ -168,6 +372,26 @@ function renderProject(name, coreVersion) {
                         description: "HTTP port the web process listens on",
                         default: 3000,
                     },
+                    // Infra connection strings live in the sys core module because every
+                    // feature shares them — one owner per variable, no duplicates.
+                    ...(full
+                        ? [
+                            {
+                                name: "MONGO_URI",
+                                type: "url",
+                                group: "database",
+                                required: true,
+                                description: "MongoDB connection string",
+                            },
+                            {
+                                name: "REDIS_URL",
+                                type: "url",
+                                group: "redis",
+                                required: true,
+                                description: "Redis connection string (queues, cache)",
+                            },
+                        ]
+                        : []),
                 ],
             })],
         ["modules/core/module.acl.ts", [
@@ -211,11 +435,14 @@ function renderProject(name, coreVersion) {
                 tulipes: { tier: "sys", priority: 10 },
                 dependencies: {
                     "@tulipes/core": core,
+                    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: [
@@ -227,28 +454,85 @@ function renderProject(name, coreVersion) {
                         description: "Minimum pino log level",
                         default: "info",
                     },
+                    {
+                        name: "CORS_ORIGINS",
+                        type: "string",
+                        group: "cors",
+                        description: 'Comma-separated browser origins allowed to call this API; "*" allows any, empty allows none (same-origin only)',
+                        default: "",
+                    },
+                    {
+                        name: "CORS_CREDENTIALS",
+                        type: "boolean",
+                        group: "cors",
+                        description: "Allow cookies and Authorization headers on cross-origin requests (cannot be combined with CORS_ORIGINS=*)",
+                        default: false,
+                    },
+                    {
+                        name: "HSTS_MAX_AGE",
+                        type: "number",
+                        group: "hardening",
+                        description: "Strict-Transport-Security max-age in seconds; 0 disables the header (browsers only honour it over HTTPS)",
+                        default: 15_552_000,
+                    },
                 ],
             })],
-        ["modules/security/helpers/security-headers.ts", [
-                `import type { RequestHandler } from "express";`,
+        ["modules/security/helpers/hardening.ts", [
+                `import type { CorsOptions } from "cors";`,
+                `import type { HelmetOptions } from "helmet";`,
+                `import type { Environment } from "@tulipes/core/env";`,
                 ``,
                 `/**`,
-                ` * Baseline hardening applied to every response before anything else`,
-                ` * runs. Dependency-free — swap in the full helmet suite here if this`,
-                ` * app ever needs it.`,
+                ` * Helmet tuned for an API rather than a web page. Its defaults assume a`,
+                ` * site serving HTML and its own assets; this one serves JSON and`,
+                ` * nothing else, so the policy can be far stricter.`,
                 ` */`,
-                `export function securityHeaders(): RequestHandler {`,
-                `  return (_req, res, next) => {`,
-                `    res.setHeader("X-Content-Type-Options", "nosniff");`,
-                `    res.setHeader("X-Frame-Options", "DENY");`,
-                `    res.setHeader("Referrer-Policy", "no-referrer");`,
-                `    // An API serves no active content; a restrictive CSP costs nothing`,
-                `    // and defuses any HTML-ish response a bug might produce.`,
-                `    res.setHeader("Content-Security-Policy", "default-src 'none'");`,
-                `    next();`,
+                `export function helmetOptions(environment: Environment): HelmetOptions {`,
+                `  const maxAge = Number(environment.get("HSTS_MAX_AGE"));`,
+                ``,
+                `  return {`,
+                `    // An API serves no active content: deny every resource type`,
+                `    // outright, which defuses any HTML-ish response a bug produces.`,
+                `    contentSecurityPolicy: {`,
+                `      useDefaults: false,`,
+                `      directives: { "default-src": ["'none'"], "frame-ancestors": ["'none'"] },`,
+                `    },`,
+                `    // Browsers only honour HSTS over HTTPS, so it is inert in local dev`,
+                `    // — but a max-age of 0 lets a deployment switch it off deliberately.`,
+                `    hsts: maxAge > 0 ? { maxAge, includeSubDomains: true } : false,`,
+                `    // Helmet defaults to SAMEORIGIN; an API is never framed at all.`,
+                `    frameguard: { action: "deny" },`,
+                `    // Irrelevant without a browsing context, and each costs a header.`,
+                `    originAgentCluster: false,`,
+                `    crossOriginEmbedderPolicy: false,`,
                 `  };`,
                 `}`,
                 ``,
+                `/**`,
+                ` * CORS from the environment, because allowed origins differ per`,
+                ` * deployment. Fail-closed: the default is an empty list, meaning no`,
+                ` * cross-origin browser may call this API until one is named.`,
+                ` */`,
+                `export function corsOptions(environment: Environment): CorsOptions {`,
+                `  const raw = String(environment.get("CORS_ORIGINS")).trim();`,
+                `  const credentials = Boolean(environment.get("CORS_CREDENTIALS"));`,
+                ``,
+                `  if (raw === "*") {`,
+                `    // "*" and credentials are mutually exclusive per the CORS spec — the`,
+                `    // browser rejects the response, so refuse the combination at boot`,
+                `    // rather than shipping an API that silently fails in production.`,
+                `    if (credentials) {`,
+                `      throw new Error(`,
+                `        'CORS_ORIGINS="*" cannot be combined with CORS_CREDENTIALS=true — list the origins explicitly',`,
+                `      );`,
+                `    }`,
+                `    return { origin: true, credentials: false };`,
+                `  }`,
+                ``,
+                `  const origins = raw.split(",").map((origin) => origin.trim()).filter(Boolean);`,
+                `  return { origin: origins, credentials };`,
+                `}`,
+                ``,
             ].join("\n")],
         ["modules/security/helpers/logger.ts", [
                 `import { pino, type Logger } from "pino";`,
@@ -278,26 +562,35 @@ function renderProject(name, coreVersion) {
                 ``,
             ].join("\n")],
         ["modules/security/routes/security.routes.ts", [
+                `import cors from "cors";`,
                 `import express from "express";`,
+                `import helmet from "helmet";`,
                 `import { pinoHttp } from "pino-http";`,
                 `import type { Ctx } from "@tulipes/core/boot";`,
                 ``,
-                `import { securityHeaders } from "../helpers/security-headers.js";`,
+                `import { corsOptions, helmetOptions } from "../helpers/hardening.js";`,
                 `import { logger } from "../helpers/logger.js";`,
                 ``,
                 `/**`,
                 ` * 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.`,
+                ` *`,
+                ` * Order matters:`,
+                ` *   helmet  — headers on every response, including errors and preflights`,
+                ` *   cors    — must answer OPTIONS preflights before anything parses a body`,
+                ` *   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 }: Ctx): void {`,
-                `  app!.use(securityHeaders());`,
+                `export default function securityRoutes({ app, Environment, config }: Ctx): void {`,
+                `  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 first — reuse`,
-                `      // it so log lines and response headers tell one story.`,
+                `      // The core module (priority 0) stamps X-Request-Id before this`,
+                `      // runs — reuse it so logs and response headers tell one story.`,
                 `      genReqId: (_req, res) => String(res.getHeader("X-Request-Id") ?? ""),`,
                 `      serializers: {`,
                 `        req: (req: { method: string; url: string }) => ({`,
@@ -310,64 +603,352 @@ function renderProject(name, coreVersion) {
                 `  );`,
                 ``,
                 `  // Body-size cap is a security control too — a parser without a limit`,
-                `  // is a memory-exhaustion invitation.`,
-                `  app!.use(express.json({ limit: "1mb" }));`,
+                `  // is a memory-exhaustion invitation. Tuned from config/app.config.ts.`,
+                `  app!.use(express.json({ limit: config.http?.bodyLimit ?? "1mb" }));`,
                 `}`,
                 ``,
             ].join("\n")],
-        // ── modules/hello — app tier: the proof route ──────────────────────────
         ["modules/hello/package.json", json({
                 name: `@app/hello`,
                 version: "0.0.0",
                 private: true,
                 type: "module",
                 tulipes: { tier: "app", priority: 100, dependsOn: [] },
-                dependencies: { "@tulipes/core": core, express: "^5" },
+                dependencies: {
+                    "@tulipes/core": core,
+                    express: "^5",
+                    ...(full ? { mongoose: "^8" } : {}),
+                },
             })],
+        ["modules/hello/meta.variables.json", json({
+                variables: [
+                    {
+                        name: "HELLO_GREETING",
+                        type: "string",
+                        group: "hello",
+                        description: "Word this module greets callers with",
+                        default: "Hello",
+                    },
+                ],
+            })],
+        ["modules/hello/module.config.ts", [
+                `import type { Ctx } from "@tulipes/core/boot";`,
+                ``,
+                `/**`,
+                ` * Runs in boot phase 6. Whatever this returns is stored at`,
+                ` * \`config.hello\` and typed by \`tulipes sync\`, so every other module`,
+                ` * reads it without importing anything from here.`,
+                ` */`,
+                `export default function helloConfig({ Environment }: Ctx) {`,
+                `  return {`,
+                `    greeting: Environment.get("HELLO_GREETING"),`,
+                `  };`,
+                `}`,
+                ``,
+                `/** After the process is fully up (server listening / worker consuming). */`,
+                `export async function onReady({ config }: Ctx): Promise<void> {`,
+                `  console.log(\`[hello] ready — greeting with "\${config.hello?.greeting}"\`);`,
+                `}`,
+                ``,
+                `/**`,
+                ` * Graceful shutdown. Hooks run in REVERSE load order, so a module can`,
+                ` * rely on its dependencies still being alive while it cleans up.`,
+                ` */`,
+                `export async function onShutdown(): Promise<void> {`,
+                `  // Close anything this module owns: timers, external clients, streams.`,
+                `}`,
+                ``,
+            ].join("\n")],
+        ["modules/hello/module.acl.ts", [
+                `import type { AclBuilder } from "@tulipes/core/acl";`,
+                ``,
+                `/**`,
+                ` * Roles are global and defined once by the sys core module; a feature`,
+                ` * module only attaches grants, and always on resources namespaced by`,
+                ` * its own name ("hello:*"). Granting the same role+resource from two`,
+                ` * modules crashes the boot.`,
+                ` */`,
+                `export default function helloAcl(acl: AclBuilder): void {`,
+                `  acl.allow("user", "hello:read");`,
+                `}`,
+                ``,
+            ].join("\n")],
+        ["modules/hello/helpers/greeting.ts", [
+                `/**`,
+                ` * Pure logic: no Express, no database, no framework. Trivial to unit`,
+                ` * test, and the framework never scans this folder — helpers are plain`,
+                ` * imports. Anything two modules need moves up to lib/.`,
+                ` */`,
+                `export function buildGreeting(greeting: string, name: string): string {`,
+                `  return \`\${greeting}, \${name}!\`;`,
+                `}`,
+                ``,
+            ].join("\n")],
+        ["modules/hello/controllers/hello.controllers.ts", [
+                `import type { Request, Response } from "express";`,
+                `import type { Ctx } from "@tulipes/core/boot";`,
+                ``,
+                `import { buildGreeting } from "../helpers/greeting.js";`,
+                ``,
+                `/**`,
+                ` * Controllers hold the work so routes stay a table of contents. The`,
+                ` * framework does not scan this folder — routes import these directly,`,
+                ` * which keeps the wiring explicit.`,
+                ` *`,
+                ` * Each controller takes ctx and RETURNS the handler. That closure is`,
+                ` * what makes it testable: pass a stub context, get a plain function.`,
+                ` */`,
+                `export function greet({ config }: Ctx) {`,
+                `  return (req: Request, res: Response): void => {`,
+                `    const name = String(req.query.name ?? "world");`,
+                `    res.json({`,
+                `      message: buildGreeting(String(config.hello?.greeting), name),`,
+                `      app: config.app?.name,`,
+                `    });`,
+                `  };`,
+                `}`,
+                ``,
+            ].join("\n")],
         ["modules/hello/routes/hello.routes.ts", [
                 `import { Router } from "express";`,
                 `import type { Ctx } from "@tulipes/core/boot";`,
+                `import { HttpError } from "@tulipes/core/http";`,
                 ``,
-                `export default function helloRoutes({ config }: Ctx): Router {`,
+                `import { greet } from "../controllers/hello.controllers.js";`,
+                ``,
+                `export default function helloRoutes(ctx: Ctx): Router {`,
                 `  const router = Router();`,
+                `  const { acl, config } = ctx;`,
+                ``,
+                `  // Built from the shared prefix, so versioning the whole API is a`,
+                `  // one-line change in config/app.config.ts.`,
+                `  const base = String(config.api?.prefix ?? "");`,
+                ``,
+                `  router.get(\`\${base}/hello\`, greet(ctx));`,
+                ``,
+                `  // Literal paths must be registered before parameterised ones, or`,
+                `  // "/hello/:name" would swallow this.`,
+                `  router.get(\`\${base}/hello/secret\`, (req, res) => {`,
+                `    // A real app resolves the role in an auth module and puts it on the`,
+                `    // request; this reads a header purely so the demo is curl-able.`,
+                `    const role = String(req.header("x-demo-role") ?? "guest");`,
+                `    if (!acl!.can(role, "hello:read")) {`,
+                `      throw new HttpError(403, \`role "\${role}" may not read hello\`);`,
+                `    }`,
+                `    res.json({ secret: "only roles granted hello:read see this" });`,
+                `  });`,
                 ``,
-                `  router.get("/hello", (_req, res) => {`,
-                `    res.json({ hello: "world", app: config.app?.name });`,
+                `  // Throwing is the whole error story — the framework's terminal`,
+                `  // handler renders it. Express 5 forwards async rejections there too.`,
+                `  router.get(\`\${base}/hello/:name\`, async (req, res) => {`,
+                `    if (req.params.name === "nobody") {`,
+                `      throw new HttpError(404, "nobody is not a greetable name");`,
+                `    }`,
+                `    res.json({ message: \`\${config.hello?.greeting}, \${req.params.name}!\` });`,
                 `  });`,
                 ``,
                 `  return router;`,
                 `}`,
                 ``,
             ].join("\n")],
-        ["README.md", [
-                `# ${name}`,
+        ["modules/hello/sockets/hello.sockets.ts", [
+                `import type { Ctx } from "@tulipes/core/boot";`,
+                `import type { SocketRegistry } from "@tulipes/core/sockets";`,
+                ``,
+                `/**`,
+                ` * Web mode only. A namespace is claimed by exactly one module; emit`,
+                ` * from anywhere with \`ctx.sockets!.of("/hello")\`.`,
+                ` *`,
+                ` * Try it: wscat -c ws://localhost:3000/hello`,
+                ` */`,
+                `export default function helloSockets({ config }: Ctx, sockets: SocketRegistry): void {`,
+                `  sockets.namespace("/hello", (nsp) => {`,
+                `    nsp.on("connection", (socket) => {`,
+                `      socket.emit("greeting", {`,
+                `        message: config.hello?.greeting,`,
+                `        online: nsp.sockets.size,`,
+                `      });`,
+                ``,
+                `      socket.on("ping", (ack: (reply: string) => void) => ack("pong"));`,
+                `    });`,
+                `  });`,
+                `}`,
+                ``,
+            ].join("\n")],
+    ];
+    // ── --full only: the contracts that need a database or redis ───────────
+    if (full) {
+        files.push(["modules/hello/models/greeting.model.ts", [
+                `import { Schema } from "mongoose";`,
+                `import type { ModelDef } from "@tulipes/core/db";`,
                 ``,
-                `A [Tulipes](https://www.npmjs.com/package/@tulipes/core) application.`,
+                `/**`,
+                ` * A model file is a DECLARATION, never a registration: the framework`,
+                ` * compiles the schema on its own connection and puts it in the model`,
+                ` * store. Never call mongoose.model() yourself.`,
+                ` *`,
+                ` * Read it anywhere the context reaches: models!.get("Greeting").`,
+                ` */`,
+                `const greetingSchema = new Schema(`,
+                `  {`,
+                `    name: { type: String, required: true, unique: true, lowercase: true, trim: true },`,
+                `    message: { type: String, required: true },`,
+                `    timesUsed: { type: Number, default: 0, min: 0 },`,
+                `  },`,
+                `  { timestamps: true },`,
+                `);`,
                 ``,
-                `## Run`,
+                `export default { name: "Greeting", schema: greetingSchema } satisfies ModelDef;`,
                 ``,
-                "```sh",
-                `corepack enable   # once per machine — activates the pinned yarn 4`,
-                `yarn install`,
-                `yarn dev          # boot the web process → http://localhost:3000/hello`,
-                "```",
+            ].join("\n")], ["modules/hello/bootstrap/seed-greetings.bootstrap.ts", [
+                `import type { Ctx } from "@tulipes/core/boot";`,
                 ``,
-                `Boots with no database and no redis: the pipeline skips engines no`,
-                `module asks for. When your first model lands, declare \`MONGO_URI\``,
-                `(type \`url\`, required) in \`modules/core/meta.variables.json\` and set`,
-                `it in \`.envs/.env.development\`; same with \`REDIS_URL\` for queues.`,
+                `/**`,
+                ` * Runs after models are registered and before the server accepts`,
+                ` * traffic — the place for indexes, seed rows and defaults.`,
+                ` *`,
+                ` * MUST be idempotent: it runs on every boot of every process, web and`,
+                ` * worker alike. Upsert; never blind-insert.`,
+                ` */`,
+                `export default async function seedGreetings({ models }: Ctx): Promise<void> {`,
+                `  const Greeting = models!.get("Greeting");`,
                 ``,
-                `## Daily commands`,
+                `  await Greeting.updateOne(`,
+                `    { name: "world" },`,
+                `    { $setOnInsert: { name: "world", message: "Hello, world!" } },`,
+                `    { upsert: true },`,
+                `  );`,
+                `}`,
                 ``,
-                `| command | does |`,
-                `|---|---|`,
-                `| \`yarn dev\` | regenerate types, run web process under tsx watch |`,
-                `| \`yarn worker\` | run the queue-consumer process (needs a queue first) |`,
-                `| \`yarn sync\` | regenerate \`types/config.d.ts\` + \`.env.example\` |`,
-                `| \`yarn check\` | validate env against every module contract — CI gate |`,
-                `| \`yarn tulipes new module <name>\` | scaffold a module |`,
+            ].join("\n")], ["modules/hello/queues/hello.queues.ts", [
+                `import type { Ctx } from "@tulipes/core/boot";`,
+                `import type { QueueRegistry } from "@tulipes/core/queues";`,
                 ``,
-            ].join("\n")],
-    ];
+                `/**`,
+                ` * ONE file describes both sides. The web process registers the queue`,
+                ` * so routes can produce into it; \`yarn worker\` turns the processor`,
+                ` * into a live consumer. Never duplicate the definition.`,
+                ` *`,
+                ` * Queue names use "." — BullMQ reserves ":" as its redis separator.`,
+                ` */`,
+                `export default function helloQueues({ models }: Ctx, queues: QueueRegistry): void {`,
+                `  queues.define("hello.count-greeting");`,
+                ``,
+                `  queues.process("hello.count-greeting", async (job) => {`,
+                `    // Jobs retry, so processors must be idempotent-safe. Pass ids in`,
+                `    // 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 } });`,
+                `    return { counted: name };`,
+                `  });`,
+                `}`,
+                ``,
+            ].join("\n")], ["modules/hello/routes/greetings.routes.ts", [
+                `import { Router } from "express";`,
+                `import type { Ctx } from "@tulipes/core/boot";`,
+                `import { HttpError } from "@tulipes/core/http";`,
+                ``,
+                `/**`,
+                ` * A module may ship several routes files; each is discovered and`,
+                ` * mounted independently. This one shows the database and the queue.`,
+                ` */`,
+                `export default function greetingsRoutes({ config, models, queues }: Ctx): Router {`,
+                `  const router = Router();`,
+                `  const base = String(config.api?.prefix ?? "");`,
+                ``,
+                `  router.get(\`\${base}/greetings\`, async (req, res) => {`,
+                `    // Pagination bounds are app-wide, so every list endpoint clamps`,
+                `    // the same way and no caller can ask for the whole table.`,
+                `    const { defaultLimit = 20, maxLimit = 100 } = config.pagination ?? {};`,
+                `    const asked = Number(req.query.limit ?? defaultLimit);`,
+                `    const limit = Math.min(Number.isFinite(asked) ? asked : defaultLimit, maxLimit);`,
+                ``,
+                `    const greetings = await models!`,
+                `      .get("Greeting")`,
+                `      .find()`,
+                `      .select("name message timesUsed -_id")`,
+                `      .limit(limit)`,
+                `      .lean();`,
+                ``,
+                `    res.json({ count: greetings.length, limit, greetings });`,
+                `  });`,
+                ``,
+                `  router.post(\`\${base}/greetings/:name/use\`, async (req, res) => {`,
+                `    const { name } = req.params;`,
+                `    const greeting = await models!.get("Greeting").findOne({ name }).lean();`,
+                `    if (!greeting) throw new HttpError(404, \`no greeting named "\${name}"\`);`,
+                ``,
+                `    // Slow or retryable work belongs in a job, not in the request.`,
+                `    // Run \`yarn worker\` in another terminal to see it processed.`,
+                `    await queues!.add("hello.count-greeting", "count", { name });`,
+                `    res.status(202).json({ name, queued: true });`,
+                `  });`,
+                ``,
+                `  return router;`,
+                `}`,
+                ``,
+            ].join("\n")]);
+    }
+    files.push(["README.md", [
+            `# ${name}`,
+            ``,
+            `A [Tulipes](https://www.npmjs.com/package/@tulipes/core) application.`,
+            ``,
+            `## Run`,
+            ``,
+            "```sh",
+            `corepack enable   # once per machine — activates the pinned yarn 4`,
+            `yarn install`,
+            `yarn dev          # boot the web process → http://localhost:3000/hello`,
+            "```",
+            ``,
+            ...(full
+                ? [
+                    `Needs mongo and redis running — see \`MONGO_URI\` and \`REDIS_URL\``,
+                    `in \`.envs/.env.development\`. Run \`yarn worker\` in a second`,
+                    `terminal to consume queued jobs.`,
+                ]
+                : [
+                    `Boots with no database and no redis: the pipeline skips engines no`,
+                    `module asks for. When your first model lands, declare \`MONGO_URI\``,
+                    `(type \`url\`, required) in \`modules/core/meta.variables.json\` and`,
+                    `set it in \`.envs/.env.development\`; same with \`REDIS_URL\` for`,
+                    `queues. \`tulipes init --full\` scaffolds all of that up front.`,
+                ]),
+            ``,
+            `## The hello module`,
+            ``,
+            `\`modules/hello\` is a worked example of every module contract — read it`,
+            `before writing your own:`,
+            ``,
+            `| File | Contract |`,
+            `|---|---|`,
+            `| \`meta.variables.json\` | the module's environment contract |`,
+            `| \`module.config.ts\` | config factory + \`onReady\` / \`onShutdown\` hooks |`,
+            `| \`module.acl.ts\` | permission grants on \`hello:*\` |`,
+            `| \`routes/*.routes.ts\` | endpoints, \`HttpError\`, ACL checks |`,
+            `| \`controllers/\` | the work; imported by routes, never scanned |`,
+            `| \`helpers/\` | pure logic, no framework |`,
+            `| \`sockets/*.sockets.ts\` | a claimed Socket.IO namespace |`,
+            ...(full
+                ? [
+                    `| \`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 |`,
+                ]
+                : []),
+            ``,
+            `## Daily commands`,
+            ``,
+            `| command | does |`,
+            `|---|---|`,
+            `| \`yarn dev\` | regenerate types, run web process under tsx watch |`,
+            `| \`yarn worker\` | run the queue-consumer process (needs a queue first) |`,
+            `| \`yarn sync\` | regenerate \`types/config.d.ts\` + \`.env.example\` |`,
+            `| \`yarn check\` | validate env against every module contract — CI gate |`,
+            `| \`yarn tulipes new module <name>\` | scaffold a module |`,
+            ``,
+        ].join("\n")]);
+    return files;
 }
 //# sourceMappingURL=init.js.map