@tulipes/core 0.1.6 → 0.1.8

package/dist/cli/init.js

@@ -96,6 +96,15 @@ function renderProject(name, coreVersion) {
                     sync: "tulipes sync",
                     check: "tulipes env:check",
                     typecheck: "tsc --noEmit",
+                    script: "tsx",
+                    "pm2:start": "pm2 start ecosystem.config.cjs",
+                    "pm2:start:staging": "pm2 start ecosystem.config.cjs --env staging",
+                    "pm2:start:production": "pm2 start ecosystem.config.cjs --env production",
+                    "pm2:stop": "pm2 stop ecosystem.config.cjs",
+                    "pm2:restart": "pm2 restart ecosystem.config.cjs",
+                    "pm2:delete": "pm2 delete ecosystem.config.cjs",
+                    "pm2:logs": "pm2 logs",
+                    "pm2:status": "pm2 status",
                 },
                 dependencies: {
                     "@tulipes/core": core,
@@ -104,6 +113,8 @@ function renderProject(name, coreVersion) {
                 devDependencies: {
                     "@types/express": "^5",
                     "@types/node": "^24",
+                    // Local convenience: servers usually install pm2 globally instead.
+                    pm2: "^6",
                     tsx: "^4",
                     typescript: "^7",
                 },
@@ -121,8 +132,71 @@ function renderProject(name, coreVersion) {
                     forceConsistentCasingInFileNames: true,
                     noEmit: true,
                 },
-                include: ["app.ts", "worker.ts", "types", "modules", "config"],
+                include: ["app.ts", "worker.ts", "types", "modules", "config", "scripts"],
             })],
+        ["ecosystem.config.cjs", [
+                `// PM2 definitions for both Tulipes processes in all three modes.`,
+                `//`,
+                `//   yarn pm2:start              development`,
+                `//   yarn pm2:start:staging      staging`,
+                `//   yarn pm2:start:production   production`,
+                `//   yarn pm2:stop | pm2:restart | pm2:delete | pm2:logs | pm2:status`,
+                `//`,
+                `// CommonJS on purpose: this app is an ESM package, and PM2 reads its`,
+                `// config with require().`,
+                ``,
+                `/**`,
+                ` * Each block repeats both variables rather than relying on PM2 merging`,
+                ` * env_<name> over env: a half-applied environment (right APP_ENV, wrong`,
+                ` * PROCESS_MODE) would start the wrong process against the wrong config,`,
+                ` * and the repetition is cheap insurance against that.`,
+                ` */`,
+                `const modes = (processMode) => ({`,
+                `  env: { APP_ENV: "development", PROCESS_MODE: processMode },`,
+                `  env_staging: { APP_ENV: "staging", PROCESS_MODE: processMode },`,
+                `  env_production: { APP_ENV: "production", PROCESS_MODE: processMode },`,
+                `});`,
+                ``,
+                `/** Shared by both apps. */`,
+                `const common = {`,
+                `  cwd: __dirname,`,
+                `  // The app runs from TypeScript, so PM2 drives it through tsx. Point`,
+                `  // script at the compiled entrypoint instead once you add a build.`,
+                `  interpreter: "./node_modules/.bin/tsx",`,
+                `  // Fork, not cluster: Socket.IO needs sticky sessions or the Redis`,
+                `  // adapter before a second instance is safe, and bootstrap tasks would`,
+                `  // run once per instance. Scale out only after wiring the adapter.`,
+                `  exec_mode: "fork",`,
+                `  instances: 1,`,
+                `  autorestart: true,`,
+                `  max_memory_restart: "512M",`,
+                `  // Graceful shutdown drains queues and closes mongo and redis. PM2's`,
+                `  // default 1.6s SIGKILL would cut that short and lose in-flight jobs.`,
+                `  kill_timeout: 10000,`,
+                `};`,
+                ``,
+                `module.exports = {`,
+                `  apps: [`,
+                `    {`,
+                `      ...common,`,
+                `      name: ${JSON.stringify(name)},`,
+                `      script: "app.ts",`,
+                `      error_file: "logs/backend-error.log",`,
+                `      out_file: "logs/backend-out.log",`,
+                `      ...modes("backend"),`,
+                `    },`,
+                `    {`,
+                `      ...common,`,
+                `      name: ${JSON.stringify(name + "-worker")},`,
+                `      script: "worker.ts",`,
+                `      error_file: "logs/worker-error.log",`,
+                `      out_file: "logs/worker-out.log",`,
+                `      ...modes("worker"),`,
+                `    },`,
+                `  ],`,
+                `};`,
+                ``,
+            ].join("\n")],
         [".yarnrc.yml", [
                 `nodeLinker: node-modules`,
                 ``,
@@ -140,6 +214,7 @@ function renderProject(name, coreVersion) {
         [".gitignore", [
                 "node_modules/",
                 "dist/",
+                "logs/",
                 "*.log",
                 "",
                 "# local env overrides — the committed .envs/.env.<mode> files hold",
@@ -272,7 +347,14 @@ function renderProject(name, coreVersion) {
                 `   * these instead of guessing the host from a request.`,
                 `   */`,
                 `  urls: {`,
-                `    api: \`http://localhost:\${Environment.get("PORT")}\`,`,
+                `    // Built from PUBLIC_DOMAIN so links generated in production —`,
+                `    // reset emails, webhook callbacks — point at the real host`,
+                `    // instead of a localhost URL that is broken everywhere but this`,
+                `    // machine. The "localhost" sentinel separates the two cases.`,
+                `    api:`,
+                `      Environment.get("PUBLIC_DOMAIN") === "localhost"`,
+                `        ? \`http://localhost:\${Environment.get("PORT")}\``,
+                `        : \`https://\${Environment.get("PUBLIC_DOMAIN")}\`,`,
                 `    frontend: "http://localhost:5173",`,
                 `  },`,
                 ``,
@@ -333,6 +415,386 @@ function renderProject(name, coreVersion) {
                 `MONGO_URI=mongodb://127.0.0.1:27017/${name}`,
                 `REDIS_URL=redis://127.0.0.1:6379`,
                 ``,
+                `# Public hostname. "localhost" means not deployed; the nginx deploy`,
+                `# script refuses until this is a real domain.`,
+                `PUBLIC_DOMAIN=localhost`,
+                ``,
+            ].join("\n")],
+        [".envs/.env.staging", [
+                `# Staging. Committed like the development file: it holds structure and`,
+                `# non-secret defaults, never credentials.`,
+                `#`,
+                `# The blanks below are intentional. Real deployments inject MONGO_URI,`,
+                `# REDIS_URL and any secret through the container environment, which`,
+                `# always wins over this file. Booting without them fails closed with a`,
+                `# report naming every missing variable — run \`yarn check\` to see it`,
+                `# without starting the app.`,
+                ``,
+                `PORT=3000`,
+                `LOG_LEVEL=info`,
+                ``,
+                `# The hostname nginx serves this app from; also the filename the`,
+                `# deploy script writes into sites-available.`,
+                `PUBLIC_DOMAIN=`,
+                `CORS_ORIGINS=`,
+                ``,
+                `# MONGO_URI=`,
+                `# REDIS_URL=`,
+                ``,
+            ].join("\n")],
+        [".envs/.env.production", [
+                `# Production. Committed like the development file: it holds structure`,
+                `# and non-secret defaults, never credentials.`,
+                `#`,
+                `# The blanks below are intentional. Real deployments inject MONGO_URI,`,
+                `# REDIS_URL and any secret through the container environment, which`,
+                `# always wins over this file. Booting without them fails closed with a`,
+                `# report naming every missing variable — run \`yarn check\` to see it`,
+                `# without starting the app.`,
+                ``,
+                `PORT=3000`,
+                `LOG_LEVEL=info`,
+                ``,
+                `# The hostname nginx serves this app from; also the filename the`,
+                `# deploy script writes into sites-available.`,
+                `PUBLIC_DOMAIN=`,
+                `CORS_ORIGINS=`,
+                ``,
+                `# MONGO_URI=`,
+                `# REDIS_URL=`,
+                ``,
+            ].join("\n")],
+        ["nginx/development.conf", [
+                `# {{DOMAIN}} — rendered from nginx/development.conf by scripts/deploy-nginx.ts.`,
+                `#`,
+                `# Development rarely needs nginx at all: \`yarn dev\` already serves on`,
+                `# {{PORT}}. This exists so the proxy layer itself can be exercised locally —`,
+                `# websocket upgrades and forwarded headers behave differently through a`,
+                `# proxy, and finding that out in staging is finding out late.`,
+                `#`,
+                `# The deploy script refuses while PUBLIC_DOMAIN is still "localhost", so`,
+                `# using this means pointing a real hostname at the machine first.`,
+                ``,
+                `server {`,
+                `    listen 80;`,
+                `    server_name {{DOMAIN}};`,
+                ``,
+                `    access_log /var/log/nginx/{{DOMAIN}}.access.log;`,
+                `    error_log  /var/log/nginx/{{DOMAIN}}.error.log;`,
+                ``,
+                `    client_max_body_size 1m;`,
+                ``,
+                `    location / {`,
+                `        proxy_pass http://127.0.0.1:{{PORT}};`,
+                `        proxy_http_version 1.1;`,
+                ``,
+                `        proxy_set_header Upgrade $http_upgrade;`,
+                `        proxy_set_header Connection $http_connection;`,
+                ``,
+                `        proxy_set_header Host              $host;`,
+                `        proxy_set_header X-Real-IP         $remote_addr;`,
+                `        proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;`,
+                `        proxy_set_header X-Forwarded-Proto $scheme;`,
+                ``,
+                `        proxy_read_timeout 3600s;`,
+                `        proxy_send_timeout 3600s;`,
+                `    }`,
+                `}`,
+                ``,
+            ].join("\n")],
+        ["nginx/staging.conf", [
+                `# {{DOMAIN}} — rendered from nginx/staging.conf by scripts/deploy-nginx.ts.`,
+                `# Placeholders are substituted at deploy time; edit this template, never the`,
+                `# copy in /etc/nginx/sites-available.`,
+                `#`,
+                `# Identical to production except for the noindex header below.`,
+                ``,
+                `server {`,
+                `    listen 80;`,
+                `    listen [::]:80;`,
+                `    server_name {{DOMAIN}};`,
+                ``,
+                `    access_log /var/log/nginx/{{DOMAIN}}.access.log;`,
+                `    error_log  /var/log/nginx/{{DOMAIN}}.error.log;`,
+                ``,
+                `    # Staging must never reach a search index, even if a link leaks.`,
+                `    add_header X-Robots-Tag "noindex, nofollow" always;`,
+                ``,
+                `    location /.well-known/acme-challenge/ {`,
+                `        root /var/www/html;`,
+                `    }`,
+                ``,
+                `    client_max_body_size 1m;`,
+                ``,
+                `    location / {`,
+                `        proxy_pass http://127.0.0.1:{{PORT}};`,
+                `        proxy_http_version 1.1;`,
+                ``,
+                `        proxy_set_header Upgrade $http_upgrade;`,
+                `        proxy_set_header Connection $http_connection;`,
+                ``,
+                `        proxy_set_header Host              $host;`,
+                `        proxy_set_header X-Real-IP         $remote_addr;`,
+                `        proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;`,
+                `        proxy_set_header X-Forwarded-Proto $scheme;`,
+                ``,
+                `        proxy_read_timeout 3600s;`,
+                `        proxy_send_timeout 3600s;`,
+                `    }`,
+                `}`,
+                ``,
+                `# TLS: see nginx/production.conf — same block, same reason it ships`,
+                `# commented out.`,
+                ``,
+            ].join("\n")],
+        ["nginx/production.conf", [
+                `# {{DOMAIN}} — rendered from nginx/production.conf by scripts/deploy-nginx.ts.`,
+                `# Placeholders are substituted at deploy time; edit this template, never the`,
+                `# copy in /etc/nginx/sites-available.`,
+                `#`,
+                `# Debian/Ubuntu layout (sites-available + sites-enabled).`,
+                ``,
+                `server {`,
+                `    listen 80;`,
+                `    listen [::]:80;`,
+                `    server_name {{DOMAIN}};`,
+                ``,
+                `    access_log /var/log/nginx/{{DOMAIN}}.access.log;`,
+                `    error_log  /var/log/nginx/{{DOMAIN}}.error.log;`,
+                ``,
+                `    # Certbot's HTTP-01 challenge, kept above the proxy so certificate`,
+                `    # issuance and renewal work without touching this file.`,
+                `    location /.well-known/acme-challenge/ {`,
+                `        root /var/www/html;`,
+                `    }`,
+                ``,
+                `    # Keep in step with config.app.ts http.bodyLimit. 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;`,
+                ``,
+                `    location / {`,
+                `        proxy_pass http://127.0.0.1:{{PORT}};`,
+                `        proxy_http_version 1.1;`,
+                ``,
+                `        # Socket.IO upgrades. Without these the handshake still succeeds and`,
+                `        # every connection silently degrades to HTTP polling.`,
+                `        proxy_set_header Upgrade $http_upgrade;`,
+                `        # Passing the client's own Connection header rather than a mapped`,
+                `        # variable: a \`map\` block here would collide the moment a second`,
+                `        # site on this server defines the same variable.`,
+                `        proxy_set_header Connection $http_connection;`,
+                ``,
+                `        proxy_set_header Host              $host;`,
+                `        proxy_set_header X-Real-IP         $remote_addr;`,
+                `        proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;`,
+                `        proxy_set_header X-Forwarded-Proto $scheme;`,
+                ``,
+                `        # Set config.http.trustProxy to true so the app reads the real`,
+                `        # client IP from the headers above.`,
+                ``,
+                `        # Long-lived websockets must outlive nginx's 60s default.`,
+                `        proxy_read_timeout 3600s;`,
+                `        proxy_send_timeout 3600s;`,
+                `    }`,
+                `}`,
+                ``,
+                `# ── TLS ────────────────────────────────────────────────────────────────────`,
+                `# Commented out on purpose: nginx -t fails on certificate paths that do not`,
+                `# exist yet, which would make the very first deploy impossible. Install the`,
+                `# certificate, then uncomment this block, redeploy with --force, and add a`,
+                `# 301 redirect to the :80 server above.`,
+                `#`,
+                `# server {`,
+                `#     listen 443 ssl;`,
+                `#     listen [::]:443 ssl;`,
+                `#     http2 on;`,
+                `#     server_name {{DOMAIN}};`,
+                `#`,
+                `#     ssl_certificate     /etc/letsencrypt/live/{{DOMAIN}}/fullchain.pem;`,
+                `#     ssl_certificate_key /etc/letsencrypt/live/{{DOMAIN}}/privkey.pem;`,
+                `#`,
+                `#     # …repeat the location / block from above…`,
+                `# }`,
+                ``,
+            ].join("\n")],
+        ["scripts/deploy-nginx.ts", [
+                `/**`,
+                ` * Install this app's nginx site config.`,
+                ` *`,
+                ` *   sudo -E APP_ENV=production yarn script scripts/deploy-nginx.ts`,
+                ` *   APP_ENV=production yarn script scripts/deploy-nginx.ts --dry-run`,
+                ` *`,
+                ` * APP_ENV picks everything at once — which template is rendered, and the`,
+                ` * domain and port rendered into it — so the three can never disagree.`,
+                ` *`,
+                ` * It boots in script mode like every other script, which means the database`,
+                ` * and redis must be reachable from wherever you run it. That is the price`,
+                ` * of every script looking the same; run --dry-run from anywhere to preview.`,
+                ` *`,
+                ` * Debian/Ubuntu only: it writes sites-available and links sites-enabled.`,
+                ` * Certificates are yours to install — the rendered conf is HTTP-only, with`,
+                ` * a commented TLS block to uncomment once they exist.`,
+                ` */`,
+                `import { execFileSync } from "node:child_process";`,
+                `import { existsSync, lstatSync, readFileSync, readlinkSync, symlinkSync, writeFileSync } from "node:fs";`,
+                `import { join } from "node:path";`,
+                ``,
+                `import { boot } from "@tulipes/core/boot";`,
+                ``,
+                `const SITES_AVAILABLE = "/etc/nginx/sites-available";`,
+                `const SITES_ENABLED = "/etc/nginx/sites-enabled";`,
+                ``,
+                `const flags = new Set(process.argv.slice(2));`,
+                `const dryRun = flags.has("--dry-run");`,
+                `const force = flags.has("--force");`,
+                ``,
+                `const rootDir = join(import.meta.dirname, "..");`,
+                `const handle = await boot({ rootDir, mode: "script" });`,
+                ``,
+                `try {`,
+                `  await deploy();`,
+                `} finally {`,
+                `  // Without this the open mongo and redis handles keep the process alive`,
+                `  // and the script appears to hang after doing its work.`,
+                `  await handle.shutdown();`,
+                `}`,
+                ``,
+                `async function deploy(): Promise<void> {`,
+                `  const { appEnv } = handle.env;`,
+                `  const domain = String(handle.env.get("PUBLIC_DOMAIN")).trim();`,
+                `  const port = Number(handle.env.get("PORT"));`,
+                ``,
+                `  const templatePath = join(rootDir, "nginx", \`\${appEnv}.conf\`);`,
+                `  if (!existsSync(templatePath)) {`,
+                `    return fail(\`no template for APP_ENV=\${appEnv} — expected nginx/\${appEnv}.conf\`);`,
+                `  }`,
+                ``,
+                `  const conf = readFileSync(templatePath, "utf8")`,
+                `    .replaceAll("{{DOMAIN}}", domain)`,
+                `    .replaceAll("{{PORT}}", String(port));`,
+                ``,
+                `  // Preview stays available everywhere, including a laptop with no nginx`,
+                `  // and a domain still set to localhost.`,
+                `  if (dryRun) {`,
+                `    console.log(\`# \${templatePath} → \${SITES_AVAILABLE}/\${domain}\\n\`);`,
+                `    console.log(conf);`,
+                `    return;`,
+                `  }`,
+                ``,
+                `  if (domain === "localhost" || domain === "") {`,
+                `    return fail(`,
+                `      \`PUBLIC_DOMAIN is "\${domain}" — set a real hostname in .envs/.env.\${appEnv} before deploying\`,`,
+                `    );`,
+                `  }`,
+                ``,
+                `  // getuid is absent on Windows; its absence is itself a "not supported here".`,
+                `  if (process.getuid?.() !== 0) {`,
+                `    return fail("must run as root to write /etc/nginx — re-run with sudo -E");`,
+                `  }`,
+                ``,
+                `  if (!existsSync(SITES_AVAILABLE)) {`,
+                `    return fail(`,
+                `      \`\${SITES_AVAILABLE} does not exist — this script targets the Debian/Ubuntu nginx layout\`,`,
+                `    );`,
+                `  }`,
+                ``,
+                `  const availablePath = join(SITES_AVAILABLE, domain);`,
+                `  if (existsSync(availablePath) && !force) {`,
+                `    return fail(`,
+                `      \`\${availablePath} already exists — re-run with --force to overwrite it (it may have been hand-tuned on this box)\`,`,
+                `    );`,
+                `  }`,
+                ``,
+                `  writeFileSync(availablePath, conf);`,
+                `  console.log(\`wrote \${availablePath}\`);`,
+                ``,
+                `  const enabledPath = join(SITES_ENABLED, domain);`,
+                `  if (!linkSite(availablePath, enabledPath)) return;`,
+                ``,
+                `  if (!run("nginx", ["-t"], "nginx rejected the configuration — nothing was reloaded")) {`,
+                `    return;`,
+                `  }`,
+                `  if (!run("systemctl", ["reload", "nginx"], "nginx reload failed")) return;`,
+                ``,
+                `  console.log(\`\\n\${domain} → 127.0.0.1:\${port} (\${appEnv}) — nginx reloaded\`);`,
+                `}`,
+                ``,
+                `/** Idempotent: a link already pointing at the right file is the goal state. */`,
+                `function linkSite(target: string, link: string): boolean {`,
+                `  if (existsSync(link) || isSymlink(link)) {`,
+                `    const current = isSymlink(link) ? readlinkSync(link) : "(a regular file)";`,
+                `    if (current === target) {`,
+                `      console.log(\`link \${link} already correct\`);`,
+                `      return true;`,
+                `    }`,
+                `    fail(\`\${link} exists and points at \${current} — remove it and re-run\`);`,
+                `    return false;`,
+                `  }`,
+                ``,
+                `  symlinkSync(target, link);`,
+                `  console.log(\`linked \${link}\`);`,
+                `  return true;`,
+                `}`,
+                ``,
+                `function isSymlink(path: string): boolean {`,
+                `  try {`,
+                `    return lstatSync(path).isSymbolicLink();`,
+                `  } catch {`,
+                `    return false;`,
+                `  }`,
+                `}`,
+                ``,
+                `function run(command: string, args: string[], message: string): boolean {`,
+                `  try {`,
+                `    execFileSync(command, args, { stdio: "inherit" });`,
+                `    return true;`,
+                `  } catch (error) {`,
+                `    // A missing binary is not a rejected config: reporting the latter would`,
+                `    // send you hunting a syntax error that does not exist.`,
+                `    const missing = (error as NodeJS.ErrnoException).code === "ENOENT";`,
+                `    fail(missing ? \`could not run "\${command}" — is it installed and on PATH?\` : message);`,
+                `    return false;`,
+                `  }`,
+                `}`,
+                ``,
+                `function fail(message: string): void {`,
+                `  console.error(\`deploy-nginx: \${message}\`);`,
+                `  process.exitCode = 1;`,
+                `}`,
+                ``,
+            ].join("\n")],
+        ["scripts/count-greetings.ts", [
+                `/**`,
+                ` * Example maintenance script. Run it with:`,
+                ` *`,
+                ` *   yarn script scripts/count-greetings.ts`,
+                ` *`,
+                ` * Script mode runs every phase the backend runs — environment, modules,`,
+                ` * config, ACL, database, models, queue producers — and then starts nothing.`,
+                ` * So a script gets exactly what a route handler gets, minus the server.`,
+                ` *`,
+                ` * The one thing to always copy from this file is the try/finally: the mongo`,
+                ` * and redis connections hold the event loop open, so a script that skips`,
+                ` * shutdown() prints its output and then hangs forever.`,
+                ` */`,
+                `import { join } from "node:path";`,
+                ``,
+                `import { boot } from "@tulipes/core/boot";`,
+                ``,
+                `const handle = await boot({ rootDir: join(import.meta.dirname, ".."), mode: "script" });`,
+                ``,
+                `try {`,
+                `  const { models, config } = handle.ctx;`,
+                ``,
+                `  const greetings = await models!.get("Greeting").find().select("name timesUsed -_id").lean();`,
+                ``,
+                `  console.log(\`\${config.app?.name} — \${greetings.length} greeting(s)\\n\`);`,
+                `  console.table(greetings);`,
+                `} finally {`,
+                `  await handle.shutdown();`,
+                `}`,
+                ``,
             ].join("\n")],
         // ── modules/core — sys tier, priority 0: the very first router ─────────
         ["modules/core/package.json", json({
@@ -368,6 +830,13 @@ function renderProject(name, coreVersion) {
                         required: true,
                         description: "Redis connection string (queues, cache)",
                     },
+                    {
+                        name: "PUBLIC_DOMAIN",
+                        type: "string",
+                        group: "deploy",
+                        description: 'Public hostname this API is served from; "localhost" means not deployed',
+                        default: "localhost",
+                    },
                 ],
             })],
         ["modules/core/module.acl.ts", [
@@ -909,6 +1378,82 @@ function renderProject(name, coreVersion) {
             `| \`yarn tulipes new module <name>\` | scaffold a module |`,
             `| \`yarn tulipes update\` | upgrade the framework everywhere it is declared |`,
             ``,
+            `## Scripts`,
+            ``,
+            `\`scripts/\` holds one-off tasks — backfills, exports, admin chores.`,
+            `They boot the app in **script mode**, which runs every phase the`,
+            `backend runs and then starts no server, so a script gets exactly what`,
+            `a route handler gets: config, ACL, models, queue producers.`,
+            ``,
+            "```sh",
+            `yarn script scripts/count-greetings.ts`,
+            "```",
+            ``,
+            `Copy the try/finally from \`scripts/count-greetings.ts\`: mongo and`,
+            `redis hold the event loop open, so a script that forgets`,
+            `\`handle.shutdown()\` prints its output and then hangs.`,
+            ``,
+            `## Deploying nginx`,
+            ``,
+            `\`nginx/{development,staging,production}.conf\` are templates with`,
+            `\`{{DOMAIN}}\` and \`{{PORT}}\` placeholders. The deploy script renders`,
+            `the one matching \`APP_ENV\`, using that same environment's`,
+            `\`PUBLIC_DOMAIN\` and \`PORT\`, so template, domain and port can never`,
+            `disagree:`,
+            ``,
+            "```sh",
+            `APP_ENV=production yarn script scripts/deploy-nginx.ts --dry-run`,
+            `sudo -E APP_ENV=production yarn script scripts/deploy-nginx.ts`,
+            "```",
+            ``,
+            `It writes \`sites-available/<domain>\`, links \`sites-enabled\`, runs`,
+            `\`nginx -t\`, then reloads. It refuses when not root, while`,
+            `\`PUBLIC_DOMAIN\` is still \`localhost\`, or when the conf already exists`,
+            `(pass \`--force\` to overwrite one). Debian/Ubuntu layout.`,
+            ``,
+            `The rendered conf is HTTP-only with the TLS block commented out —`,
+            `\`nginx -t\` fails on certificate paths that do not exist yet, which`,
+            `would make the first deploy impossible. Install the certificate,`,
+            `uncomment the block, redeploy with \`--force\`.`,
+            ``,
+            `## Running under PM2`,
+            ``,
+            `\`ecosystem.config.cjs\` defines both processes — the backend and the`,
+            `queue worker — in all three modes:`,
+            ``,
+            "```sh",
+            `yarn pm2:start              # development`,
+            `yarn pm2:start:staging`,
+            `yarn pm2:start:production`,
+            ``,
+            `yarn pm2:status             # what is running`,
+            `yarn pm2:logs               # tail both processes`,
+            `yarn pm2:restart            # reload code`,
+            `yarn pm2:stop               # stop, keep them in the process list`,
+            `yarn pm2:delete             # remove from the process list`,
+            "```",
+            ``,
+            `Switching environment requires a restart carrying the flag, because`,
+            `PM2 remembers the environment a process was started with:`,
+            `\`pm2 restart ecosystem.config.cjs --env production\`.`,
+            ``,
+            `\`.envs/\` holds one file per mode. All three are committed because they`,
+            `carry structure and non-secret defaults only — connection strings and`,
+            `secrets are injected by the server or container, which always wins over`,
+            `the file. \`yarn check\` validates the current environment without`,
+            `booting, so a deploy can fail on configuration before it fails on`,
+            `traffic.`,
+            ``,
+            `PM2 is a devDependency so the scripts work straight after install;`,
+            `servers usually install it globally instead (\`npm i -g pm2\`), in`,
+            `which case the same scripts still work.`,
+            ``,
+            `Two defaults worth knowing: processes run in **fork** mode with a`,
+            `single instance, because Socket.IO needs sticky sessions or the Redis`,
+            `adapter before a second instance is safe; and \`kill_timeout\` is 10s so`,
+            `graceful shutdown can drain queues and close mongo and redis before`,
+            `PM2 sends SIGKILL.`,
+            ``,
         ].join("\n")]);
     return files;
 }