create-skweb 3.2.0 → 3.3.1

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # create-skweb
 
+## 3.3.1
+
+### Patch Changes
+
+- 修复生成项目问题：.env.example 文件生成、startCronWorker 改为 bootstrap、去除 ts-nocheck 标记、缩短输出文本
+
+## 3.3.0
+
+### Minor Changes
+
+- 重构模板结构：入口文件重命名为 web-app/cron-app，新增 web-framework/cron-framework 单例文件，移除冗余的 index 和 services/database
+
 ## 3.2.0
 
 ### Minor Changes

package/dist/cli.js

@@ -32,29 +32,22 @@ async function createProject(options) {
             await fs.mkdirs(path.join(targetDir, fileName));
             continue;
         }
-        // 处理 auth-后缀：例如 src/app.auth-static.js -> 生成 src/app.js
-        // .env.example.auth-static -> 生成 .env.example
-        let outputName = fileName;
-        const authMatch = fileName.match(/^(.*?)\.auth-(static|jwks)(\.[^.]+)?$/);
-        if (authMatch) {
-            const [, base, fileAuth, ext] = authMatch;
-            if (fileAuth !== auth) {
-                // 不匹配用户选择的 auth，跳过
-                continue;
-            }
-            outputName = ext ? `${base}${ext}` : base;
-        }
-        else {
-            // 没有 auth- 后缀的 .env.example：跳过（避免与 auth- 版本冲突）
-            if (fileName === '.env.example' || fileName.endsWith('/.env.example')) {
-                continue;
-            }
+        // 跳过 auth- 后缀的文件（已合并到统一模板）
+        if (/\.auth-(static|jwks)(\.[^.]+)?$/.test(fileName)) {
+            continue;
         }
+        const outputName = fileName;
         let content = await fs.readFile(srcPath, 'utf-8');
+        // 处理条件块：{{#if_eq auth "static"}}...{{else}}...{{/if_eq}}
+        content = content.replace(/\{\{#if_eq auth "(static|jwks)"\}\}([\s\S]*?)(?:\{\{else\}\}([\s\S]*?))?\{\{\/if_eq\}\}/g, (_match, value, mainContent, elseContent) => {
+            return value === auth ? mainContent : (elseContent || '');
+        });
         content = content
             .replace(/\{\{name\}\}/g, name)
             .replace(/\{\{description\}\}/g, description)
             .replace(/\{\{auth\}\}/g, auth);
+        // 移除 ts-nocheck 标记
+        content = content.replace(/^\/\/ @ts-nocheck\s*\n/gm, '');
         const destPath = path.join(targetDir, outputName);
         await fs.writeFile(destPath, content);
     }
@@ -88,44 +81,15 @@ function printBanner() {
 function printSuccess(name, dest) {
     const projectPath = path.join(path.resolve(dest), name);
     console.log(`
-╔════════════════════════════════════════════════════════════════════╗
-║                         项目创建成功！                               ║
-╚════════════════════════════════════════════════════════════════════╝
-
-项目名称: ${name}
-项目路径: ${projectPath}
+项目创建成功！
 
-接下来可以执行:
+名称: ${name}
+路径: ${projectPath}
 
+接下来执行:
   cd ${name}
-
-  # 复制环境变量模板并按需修改
   cp .env.example .env
-
-  # 开发模式运行
-  npm run start:dev
-
-  # 生产模式运行 (需要先构建)
-  npm run build
-  npm run start
-
-  # 查看日志
-  npm run logs
-
-  # 停止服务
-  npm run stop
-
-  # 重启服务
-  npm run restart
-
-项目特性:
-  ✅ TypeScript/MJS/CJS 支持
-  ✅ @dotenvx/dotenvx 环境变量管理
-  ✅ PM2 进程管理
-  ✅ SKWeb Express 集成
-  ✅ Keycloak/JWKS 鉴权 (可选)
-  ✅ ESLint 代码检查
-  ✅ Mocha 测试框架
+  npm run web:dev
 `);
 }
 

package/dist/index.js

@@ -27,29 +27,22 @@ async function createProject(options) {
             await fs.mkdirs(path.join(targetDir, fileName));
             continue;
         }
-        // 处理 auth-后缀：例如 src/app.auth-static.js -> 生成 src/app.js
-        // .env.example.auth-static -> 生成 .env.example
-        let outputName = fileName;
-        const authMatch = fileName.match(/^(.*?)\.auth-(static|jwks)(\.[^.]+)?$/);
-        if (authMatch) {
-            const [, base, fileAuth, ext] = authMatch;
-            if (fileAuth !== auth) {
-                // 不匹配用户选择的 auth，跳过
-                continue;
-            }
-            outputName = ext ? `${base}${ext}` : base;
-        }
-        else {
-            // 没有 auth- 后缀的 .env.example：跳过（避免与 auth- 版本冲突）
-            if (fileName === '.env.example' || fileName.endsWith('/.env.example')) {
-                continue;
-            }
+        // 跳过 auth- 后缀的文件（已合并到统一模板）
+        if (/\.auth-(static|jwks)(\.[^.]+)?$/.test(fileName)) {
+            continue;
         }
+        const outputName = fileName;
         let content = await fs.readFile(srcPath, 'utf-8');
+        // 处理条件块：{{#if_eq auth "static"}}...{{else}}...{{/if_eq}}
+        content = content.replace(/\{\{#if_eq auth "(static|jwks)"\}\}([\s\S]*?)(?:\{\{else\}\}([\s\S]*?))?\{\{\/if_eq\}\}/g, (_match, value, mainContent, elseContent) => {
+            return value === auth ? mainContent : (elseContent || '');
+        });
         content = content
             .replace(/\{\{name\}\}/g, name)
             .replace(/\{\{description\}\}/g, description)
             .replace(/\{\{auth\}\}/g, auth);
+        // 移除 ts-nocheck 标记
+        content = content.replace(/^\/\/ @ts-nocheck\s*\n/gm, '');
         const destPath = path.join(targetDir, outputName);
         await fs.writeFile(destPath, content);
     }
@@ -83,44 +76,15 @@ function printBanner() {
 function printSuccess(name, dest) {
     const projectPath = path.join(path.resolve(dest), name);
     console.log(`
-╔════════════════════════════════════════════════════════════════════╗
-║                         项目创建成功！                               ║
-╚════════════════════════════════════════════════════════════════════╝
-
-项目名称: ${name}
-项目路径: ${projectPath}
+项目创建成功！
 
-接下来可以执行:
+名称: ${name}
+路径: ${projectPath}
 
+接下来执行:
   cd ${name}
-
-  # 复制环境变量模板并按需修改
   cp .env.example .env
-
-  # 开发模式运行
-  npm run start:dev
-
-  # 生产模式运行 (需要先构建)
-  npm run build
-  npm run start
-
-  # 查看日志
-  npm run logs
-
-  # 停止服务
-  npm run stop
-
-  # 重启服务
-  npm run restart
-
-项目特性:
-  ✅ TypeScript/MJS/CJS 支持
-  ✅ @dotenvx/dotenvx 环境变量管理
-  ✅ PM2 进程管理
-  ✅ SKWeb Express 集成
-  ✅ Keycloak/JWKS 鉴权 (可选)
-  ✅ ESLint 代码检查
-  ✅ Mocha 测试框架
+  npm run web:dev
 `);
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-skweb",
-  "version": "3.2.0",
+  "version": "3.3.1",
   "description": "Create a new SKWeb project with TypeScript, CJS, or MJS support",
   "type": "module",
   "main": "dist/index.js",

package/src/index.ts

@@ -42,31 +42,31 @@ export async function createProject(options: CreateOptions): Promise<void> {
       continue
     }
 
-    // 处理 auth-后缀：例如 src/app.auth-static.js -> 生成 src/app.js
-    // .env.example.auth-static -> 生成 .env.example
-    let outputName = fileName
-    const authMatch = fileName.match(/^(.*?)\.auth-(static|jwks)(\.[^.]+)?$/)
-    if (authMatch) {
-      const [, base, fileAuth, ext] = authMatch
-      if (fileAuth !== auth) {
-        // 不匹配用户选择的 auth，跳过
-        continue
-      }
-      outputName = ext ? `${base}${ext}` : base
-    } else {
-      // 没有 auth- 后缀的 .env.example：跳过（避免与 auth- 版本冲突）
-      if (fileName === '.env.example' || fileName.endsWith('/.env.example')) {
-        continue
-      }
+    // 跳过 auth- 后缀的文件（已合并到统一模板）
+    if (/\.auth-(static|jwks)(\.[^.]+)?$/.test(fileName)) {
+      continue
     }
 
+    const outputName = fileName
+
     let content = await fs.readFile(srcPath, 'utf-8')
 
+    // 处理条件块：{{#if_eq auth "static"}}...{{else}}...{{/if_eq}}
+    content = content.replace(
+      /\{\{#if_eq auth "(static|jwks)"\}\}([\s\S]*?)(?:\{\{else\}\}([\s\S]*?))?\{\{\/if_eq\}\}/g,
+      (_match: string, value: string, mainContent: string, elseContent: string) => {
+        return value === auth ? mainContent : (elseContent || '')
+      }
+    )
+
     content = content
       .replace(/\{\{name\}\}/g, name)
       .replace(/\{\{description\}\}/g, description)
       .replace(/\{\{auth\}\}/g, auth)
 
+    // 移除 ts-nocheck 标记
+    content = content.replace(/^\/\/ @ts-nocheck\s*\n/gm, '')
+
     const destPath = path.join(targetDir, outputName)
     await fs.writeFile(destPath, content)
   }
@@ -108,43 +108,14 @@ export function printBanner(): void {
 export function printSuccess(name: string, dest: string): void {
   const projectPath = path.join(path.resolve(dest), name)
   console.log(`
-╔════════════════════════════════════════════════════════════════════╗
-║                         项目创建成功！                               ║
-╚════════════════════════════════════════════════════════════════════╝
+项目创建成功！
 
-项目名称: ${name}
-项目路径: ${projectPath}
-
-接下来可以执行:
+名称: ${name}
+路径: ${projectPath}
 
+接下来执行:
   cd ${name}
-
-  # 复制环境变量模板并按需修改
   cp .env.example .env
-
-  # 开发模式运行
-  npm run start:dev
-
-  # 生产模式运行 (需要先构建)
-  npm run build
-  npm run start
-
-  # 查看日志
-  npm run logs
-
-  # 停止服务
-  npm run stop
-
-  # 重启服务
-  npm run restart
-
-项目特性:
-  ✅ TypeScript/MJS/CJS 支持
-  ✅ @dotenvx/dotenvx 环境变量管理
-  ✅ PM2 进程管理
-  ✅ SKWeb Express 集成
-  ✅ Keycloak/JWKS 鉴权 (可选)
-  ✅ ESLint 代码检查
-  ✅ Mocha 测试框架
+  npm run web:dev
 `)
 }

package/templates/cjs/{.env.example.auth-jwks → .env.example}

@@ -38,6 +38,12 @@ REDIS_DB=0
 # (Production is always disabled to avoid exposing internal API details.)
 SWAGGER_ENABLED=true
 
+{{#if_eq auth "static"}}
+# ---------- Auth: static (HS256 shared secret) ----------
+# [REQUIRED in production] Use a strong random string, e.g. `openssl rand -hex 32`
+JWT_SECRET=please-change-this-in-production
+JWT_EXPIRES_IN=7d
+{{else}}
 # ---------- Auth: jwks (OIDC compatible) ----------
 # Works with any OIDC-compliant IdP. Common issuer formats:
 #   Keycloak:  https://kc.example.com/realms/myrealm
@@ -50,6 +56,7 @@ SWAGGER_ENABLED=true
 OIDC_ISSUER=
 OIDC_AUDIENCE=
 OIDC_JWKS_URI=
+{{/if_eq}}
 
 # ---------- Logging ----------
 # error | warn | info | http | verbose | debug | silly

package/templates/cjs/ecosystem.config.js

@@ -2,7 +2,7 @@ module.exports = {
   apps: [
     {
       name: '{{name}}-web',
-      script: 'src/index.js',
+      script: 'src/web-app.js',
       instances: 'max',
       exec_mode: 'cluster',
       env: {
@@ -16,7 +16,7 @@ module.exports = {
     },
     {
       name: '{{name}}-cron',
-      script: 'src/cronWorker.js',
+      script: 'src/cron-app.js',
       instances: 1,
       exec_mode: 'fork',
       autorestart: true,

package/templates/cjs/package.json

@@ -9,8 +9,8 @@
     "restart": "pm2 restart all",
     "delete": "pm2 delete all",
     "logs": "pm2 logs",
-    "web:dev": "npx dotenvx run -- node --watch src/index.js",
-    "cron:dev": "npx dotenvx run -- node --watch src/cronWorker.js",
+    "web:dev": "npx dotenvx run -- node --watch src/web-app.js",
+    "cron:dev": "npx dotenvx run -- node --watch src/cron-app.js",
     "seed": "npx dotenvx run -- node src/commands/seed.js",
     "migrate": "npx dotenvx run -- node src/commands/migrate.js",
     "build": "cp -r src dist",
@@ -22,13 +22,13 @@
   "dependencies": {
     "@dotenvx/dotenvx": "^1.75.1",
     "http-errors": "^2.0.1",
-    "skweb-express": "^2.0.3",
+    "skweb-express": "^2.0.4",
     "skweb-express-jwt": "^3.0.0",
     "skweb-express-logger": "^2.0.0",
     "skweb-sequelize": "^2.0.0",
     "skweb-redis": "^2.0.0",
     "skweb-cron": "^2.0.0",
-    "skweb-framework": "^2.1.0",
+    "skweb-framework": "^2.1.1",
     "skweb-plugin": "^2.1.1",
     "skweb-util": "^2.0.0",
     "winston": "^3.19.0",

package/templates/cjs/src/controllers/user.js

@@ -1,7 +1,7 @@
 const createHttpError = require('http-errors')
-const { db } = require('../services/database.js')
+const { framework } = require('../web-framework.js')
 
-const { SysUser } = db.sequelize.models
+const { SysUser } = framework.models
 
 /**
  * @swagger

package/templates/cjs/src/cron-app.js

@@ -0,0 +1,40 @@
+require('dotenv/config')
+
+const path = require('path')
+const { framework } = require('./cron-framework.js')
+const { logger } = require('./utils/logger.js')
+const { checkRequiredEnv } = require('./utils/config.js')
+
+async function bootstrap() {
+  logger.info('[cron-worker] Starting cron worker process...')
+
+  if (!checkRequiredEnv()) {
+    logger.error('[cron-worker] Configuration validation failed, exiting...')
+    process.exit(1)
+  }
+
+  await framework.setup({
+    modelsDir: path.join(__dirname, './models'),
+    cronActionsDir: path.join(__dirname, './cronActions')
+  })
+  await framework.start()
+  logger.info('[cron-worker] Cron worker started')
+
+  process.on('uncaughtException', (err) => {
+    logger.error(`[cron-worker] uncaughtException: ${err.stack || err.message}`)
+    process.exit(1)
+  })
+  process.on('unhandledRejection', (reason) => {
+    logger.error(`[cron-worker] unhandledRejection: ${reason instanceof Error ? reason.stack : String(reason)}`)
+    process.exit(1)
+  })
+}
+
+if (require.main === module) {
+  bootstrap().catch((err) => {
+    logger.error('[cron-worker] Fatal error:', err)
+    process.exit(1)
+  })
+}
+
+module.exports = { bootstrap }

package/templates/cjs/src/cron-framework.js

@@ -0,0 +1,44 @@
+// @ts-nocheck
+const { CronFramework } = require('skweb-framework')
+const { logger } = require('./utils/logger.js')
+
+const framework = new CronFramework({
+  db: {
+    host: process.env.DB_HOST || '127.0.0.1',
+    port: Number(process.env.DB_PORT) || 3306,
+    username: process.env.DB_USER || 'root',
+    password: process.env.DB_PASS || '',
+    database: process.env.DB_NAME || 'test-project',
+    dialect: process.env.DB_DIALECT || 'mysql',
+    charset: process.env.DB_CHARSET || 'utf8mb4',
+    underscored: true,
+    logging: process.env.DEBUG_DB === 'true'
+  },
+  redis: {
+    host: process.env.REDIS_HOST || '127.0.0.1',
+    port: Number(process.env.REDIS_PORT) || 6379,
+    password: process.env.REDIS_PASSWORD || undefined
+  },
+  channel: 'cron:task:cmd',
+  logger,
+  onSaveTask: async (taskData) => {
+    const SysCronTask = framework.db?.sequelize?.models.SysCronTask
+    if (SysCronTask) {
+      await SysCronTask.update(
+        { cache: taskData.cache, data: taskData.data },
+        { where: { id: taskData.taskId } }
+      )
+    }
+  },
+  loadTasks: async () => {
+    const SysCronTask = framework.db?.sequelize?.models.SysCronTask
+    if (!SysCronTask) return []
+    return (await SysCronTask.findAll()).map((t) => ({
+      id: String(t.id),
+      cronTime: t.cronTime,
+      method: t.method
+    }))
+  }
+})
+
+module.exports = { framework }

package/templates/cjs/src/{swagger.auth-jwks.js → swagger.js}

@@ -1,3 +1,4 @@
+// @ts-nocheck
 'use strict'
 
 const path = require('path')
@@ -18,6 +19,13 @@ function buildOpenApiSpec() {
       ],
       components: {
         securitySchemes: {
+          {{#if_eq auth "static"}}
+          bearerAuth: {
+            type: 'http',
+            scheme: 'bearer',
+            bearerFormat: 'JWT'
+          }
+          {{else}}
           oidcAuth: {
             type: 'openIdConnect',
             openIdConnectUrl: process.env.OIDC_JWKS_URI
@@ -26,6 +34,7 @@ function buildOpenApiSpec() {
                   ? `${process.env.OIDC_ISSUER.replace(/\/$/, '')}/.well-known/openid-configuration`
                   : undefined)
           }
+          {{/if_eq}}
         }
       }
     },

package/templates/cjs/src/utils/{config.auth-jwks.js → config.js}

@@ -1,3 +1,4 @@
+// @ts-nocheck
 const { logger } = require('./logger.js')
 
 function validateConfig() {
@@ -38,6 +39,18 @@ function validateConfig() {
   }
 }
 
+{{#if_eq auth "static"}}
+function checkJwtSecret() {
+  if (process.env.JWT_SECRET === 'please-change-this-in-production' || !process.env.JWT_SECRET) {
+    if (process.env.NODE_ENV === 'production') {
+      logger.error('[config] JWT_SECRET must be set in production!')
+      return false
+    }
+    logger.warn('[config] WARNING: JWT_SECRET is using default value, please change in production!')
+  }
+  return true
+}
+{{else}}
 function checkOIDCConfig() {
   const issuer = process.env.OIDC_ISSUER
   const jwksUri = process.env.OIDC_JWKS_URI
@@ -50,6 +63,7 @@ function checkOIDCConfig() {
   }
   return true
 }
+{{/if_eq}}
 
 function checkRequiredEnv() {
   const result = validateConfig()
@@ -64,4 +78,8 @@ function checkRequiredEnv() {
   return true
 }
 
+{{#if_eq auth "static"}}
+module.exports = { validateConfig, checkJwtSecret, checkRequiredEnv }
+{{else}}
 module.exports = { validateConfig, checkOIDCConfig, checkRequiredEnv }
+{{/if_eq}}

package/templates/cjs/src/{app.auth-jwks.js → web-app.js}

@@ -1,3 +1,4 @@
+// @ts-nocheck
 require('dotenv/config')
 
 const path = require('path')
@@ -5,11 +6,25 @@ const express = require('skweb-express').default
 const expressLogger = require('skweb-express-logger').default
 const expressErrorHandler = require('skweb-express-logger').errorHandler
 const swaggerUi = require('swagger-ui-express')
-const { WebFramework } = require('skweb-framework')
+const { framework } = require('./web-framework.js')
 const { logger } = require('./utils/logger.js')
-const { checkRequiredEnv, checkOIDCConfig } = require('./utils/config.js')
+const { checkRequiredEnv{{#if_eq auth "static"}}, checkJwtSecret{{/if_eq}}{{#if_eq auth "jwks"}}, checkOIDCConfig{{/if_eq}} } = require('./utils/config.js')
 const { buildOpenApiSpec } = require('./swagger.js')
 
+{{#if_eq auth "static"}}
+/**
+ * JWT 配置（static 模式，HS256 共享密钥）。
+ */
+function buildJwtOptions() {
+  return {
+    provider: 'static',
+    secret: process.env.JWT_SECRET || 'please-change-this-in-production',
+    algorithms: ['HS256'],
+    sign: { expiresIn: process.env.JWT_EXPIRES_IN || '7d' },
+    requestProperty: 'resolvedToken'
+  }
+}
+{{else}}
 /**
  * JWT 配置（jwks 模式，通过 OIDC 兼容的 JWKS 端点验证 RS256 签名）。
  */
@@ -28,7 +43,12 @@ function buildJwtOptions() {
     requestProperty: 'resolvedToken'
   }
 }
+{{/if_eq}}
 
+/**
+ * Swagger UI 仅在 NODE_ENV 为 development / test，且 SWAGGER_ENABLED !== 'false' 时启用。
+ * 生产环境（production / unset）默认禁用，避免暴露内部 API 细节。
+ */
 function shouldEnableSwagger() {
   const env = (process.env.NODE_ENV || '').toLowerCase()
   if (env !== 'development' && env !== 'test') return false
@@ -43,29 +63,18 @@ async function bootstrap() {
     logger.error('[app] Configuration validation failed, exiting...')
     process.exit(1)
   }
+  {{#if_eq auth "static"}}
+  if (!checkJwtSecret()) {
+    logger.error('[app] JWT configuration validation failed, exiting...')
+    process.exit(1)
+  }
+  {{else}}
   if (!checkOIDCConfig()) {
     logger.error('[app] OIDC configuration validation failed, exiting...')
     process.exit(1)
   }
+  {{/if_eq}}
 
-  const framework = new WebFramework({
-    db: {
-      host: process.env.DB_HOST || '127.0.0.1',
-      port: Number(process.env.DB_PORT) || 3306,
-      username: process.env.DB_USER || 'root',
-      password: process.env.DB_PASS || '',
-      database: process.env.DB_NAME || 'test-project',
-      dialect: process.env.DB_DIALECT || 'mysql',
-      charset: process.env.DB_CHARSET || 'utf8mb4',
-      underscored: true,
-      logging: process.env.DEBUG_DB === 'true' ? (msg) => logger.debug(msg) : false
-    },
-    redis: {
-      host: process.env.REDIS_HOST || '127.0.0.1',
-      port: Number(process.env.REDIS_PORT) || 6379,
-      password: process.env.REDIS_PASSWORD || undefined
-    }
-  })
   const app = framework.createApp()
 
   await framework.setup({
@@ -86,7 +95,11 @@ async function bootstrap() {
   app.setJWT('default', jwtOptions)
   app.setJwtHintHeader('JwtHint')
 
-  logger.info(`[app] JWT auth provider: jwks (issuer: ${jwtOptions.jwks.issuer || jwtOptions.jwks.jwksUri})`)
+  {{#if_eq auth "static"}}
+  logger.info('[app] JWT auth provider: static (HS256)')
+  {{else}}
+  logger.info(`[app] JWT auth provider: jwks (issuer: ${jwtOptions.jwks?.issuer || jwtOptions.jwks?.jwksUri})`)
+  {{/if_eq}}
 
   app.use(expressLogger())
   app.use(express.static(path.join(__dirname, '..', 'public')))

package/templates/cjs/src/web-framework.js

@@ -0,0 +1,23 @@
+// @ts-nocheck
+const { WebFramework } = require('skweb-framework')
+
+const framework = new WebFramework({
+  db: {
+    host: process.env.DB_HOST || '127.0.0.1',
+    port: Number(process.env.DB_PORT) || 3306,
+    username: process.env.DB_USER || 'root',
+    password: process.env.DB_PASS || '',
+    database: process.env.DB_NAME || 'test-project',
+    dialect: process.env.DB_DIALECT || 'mysql',
+    charset: process.env.DB_CHARSET || 'utf8mb4',
+    underscored: true,
+    logging: process.env.DEBUG_DB === 'true'
+  },
+  redis: {
+    host: process.env.REDIS_HOST || '127.0.0.1',
+    port: Number(process.env.REDIS_PORT) || 6379,
+    password: process.env.REDIS_PASSWORD || undefined
+  }
+})
+
+module.exports = { framework }

package/templates/{ts/.env.example.auth-jwks → mjs/.env.example}

@@ -38,6 +38,12 @@ REDIS_DB=0
 # (Production is always disabled to avoid exposing internal API details.)
 SWAGGER_ENABLED=true
 
+{{#if_eq auth "static"}}
+# ---------- Auth: static (HS256 shared secret) ----------
+# [REQUIRED in production] Use a strong random string, e.g. `openssl rand -hex 32`
+JWT_SECRET=please-change-this-in-production
+JWT_EXPIRES_IN=7d
+{{else}}
 # ---------- Auth: jwks (OIDC compatible) ----------
 # Works with any OIDC-compliant IdP. Common issuer formats:
 #   Keycloak:  https://kc.example.com/realms/myrealm
@@ -50,6 +56,7 @@ SWAGGER_ENABLED=true
 OIDC_ISSUER=
 OIDC_AUDIENCE=
 OIDC_JWKS_URI=
+{{/if_eq}}
 
 # ---------- Logging ----------
 # error | warn | info | http | verbose | debug | silly