@tulipes/core 0.1.3 → 0.1.5

package/dist/cli/init.js

@@ -1,16 +1,18 @@
-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]` — 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: config with lifecycle hooks,
+ * ACL grants, routes, a controller, a helper, a model, a bootstrap task,
+ * a queue with its processor, and a socket namespace.
+ *
+ * The generated app therefore needs mongo and redis running — models and
+ * queues cannot work without them, and the boot refuses rather than
+ * degrading quietly.
  */
 export async function runInit(rootDir, target) {
     const dir = resolve(rootDir, target ?? ".");
@@ -28,6 +30,7 @@ export async function runInit(rootDir, target) {
         writeFileSync(filePath, content);
         console.log(`  create ${relPath}`);
     }
+    copyAgentGuides(dir);
     console.log([
         "",
         `Project "${name}" is ready. Next:`,
@@ -39,8 +42,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.",
+        "Needs mongo and redis running — see MONGO_URI / REDIS_URL in",
+        ".envs/.env.development. Run `yarn worker` in a second terminal to",
+        "consume queued jobs.",
     ].filter((line) => line !== undefined).join("\n"));
 }
 /**
@@ -49,10 +53,39 @@ 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";
@@ -60,7 +93,7 @@ function sanitizeName(raw) {
 const json = (value) => JSON.stringify(value, null, 2) + "\n";
 function renderProject(name, coreVersion) {
     const core = `^${coreVersion}`;
-    return [
+    const files = [
         ["package.json", json({
                 name,
                 private: true,
@@ -130,7 +163,7 @@ function renderProject(name, coreVersion) {
         ["app.ts", [
                 `import { boot } from "@tulipes/core/boot";`,
                 ``,
-                `await boot({ rootDir: import.meta.dirname, mode: "web" });`,
+                `await boot({ rootDir: import.meta.dirname, mode: "backend" });`,
                 ``,
             ].join("\n")],
         ["worker.ts", [
@@ -305,6 +338,13 @@ 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`,
+                ``,
+                `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({
@@ -321,9 +361,25 @@ function renderProject(name, coreVersion) {
                         name: "PORT",
                         type: "number",
                         group: "http",
-                        description: "HTTP port the web process listens on",
+                        description: "HTTP port the backend 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.
+                    {
+                        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", [
@@ -367,11 +423,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: [
@@ -383,28 +442,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";`,
@@ -434,26 +550,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 }) => ({`,
@@ -466,64 +591,336 @@ 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",
+                    mongoose: "^8",
+                },
             })],
-        ["modules/hello/routes/hello.routes.ts", [
-                `import { Router } from "express";`,
+        ["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";`,
                 ``,
-                `export default function helloRoutes({ config }: Ctx): Router {`,
-                `  const router = Router();`,
+                `/**`,
+                ` * 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"),`,
+                `  };`,
+                `}`,
                 ``,
-                `  router.get("/hello", (_req, res) => {`,
-                `    res.json({ hello: "world", app: config.app?.name });`,
-                `  });`,
+                `/** 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}"\`);`,
+                `}`,
                 ``,
-                `  return router;`,
+                `/**`,
+                ` * 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")],
-        ["README.md", [
-                `# ${name}`,
+        ["modules/hello/module.acl.ts", [
+                `import type { AclBuilder } from "@tulipes/core/acl";`,
                 ``,
-                `A [Tulipes](https://www.npmjs.com/package/@tulipes/core) application.`,
+                `/**`,
+                ` * 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");`,
+                `}`,
                 ``,
-                `## Run`,
+            ].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}!\`;`,
+                `}`,
                 ``,
-                "```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/controllers/hello.controllers.ts", [
+                `import type { Request, Response } from "express";`,
+                `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.`,
+                `import { buildGreeting } from "../helpers/greeting.js";`,
                 ``,
-                `## Daily commands`,
+                `/**`,
+                ` * 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,`,
+                `    });`,
+                `  };`,
+                `}`,
                 ``,
-                `| 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/routes/hello.routes.ts", [
+                `import { Router } from "express";`,
+                `import type { Ctx } from "@tulipes/core/boot";`,
+                `import { HttpError } from "@tulipes/core/http";`,
+                ``,
+                `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" });`,
+                `  });`,
+                ``,
+                `  // 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")],
+        ["modules/hello/sockets/hello.sockets.ts", [
+                `import type { Ctx } from "@tulipes/core/boot";`,
+                `import type { SocketRegistry } from "@tulipes/core/sockets";`,
+                ``,
+                `/**`,
+                ` * Backend 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")],
     ];
+    // ── the contracts that need a database or redis ────────────────────────
+    files.push(["modules/hello/models/greeting.model.ts", [
+            `import { Schema } from "mongoose";`,
+            `import type { ModelDef } from "@tulipes/core/db";`,
+            ``,
+            `/**`,
+            ` * 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 },`,
+            `);`,
+            ``,
+            `export default { name: "Greeting", schema: greetingSchema } satisfies ModelDef;`,
+            ``,
+        ].join("\n")], ["modules/hello/bootstrap/seed-greetings.bootstrap.ts", [
+            `import type { Ctx } from "@tulipes/core/boot";`,
+            ``,
+            `/**`,
+            ` * 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, backend and`,
+            ` * worker alike. Upsert; never blind-insert.`,
+            ` */`,
+            `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 },`,
+            `  );`,
+            `}`,
+            ``,
+        ].join("\n")], ["modules/hello/queues/hello.queues.ts", [
+            `import type { Ctx } from "@tulipes/core/boot";`,
+            `import type { QueueRegistry } from "@tulipes/core/queues";`,
+            ``,
+            `/**`,
+            ` * ONE file describes both sides. The backend 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 backend process → http://localhost:3000/hello`,
+            "```",
+            ``,
+            `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.`,
+            ``,
+            `## 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 |`,
+            `| \`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 backend 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