create-skweb 3.1.0 → 3.2.0

package/.turbo/turbo-test.log

@@ -1,4 +1,69 @@
 
-> create-skweb@1.2.1 test
+> create-skweb@3.2.0 test
 > mocha test/**/*.mjs
 
+
+
+  create-skweb
+    createProject()
+      ✔ should create TypeScript project from template
+      ✔ should create MJS project from template
+      ✔ should create CJS project from template
+      ✔ should reject non-empty destination directory
+      ✔ should include winston in all templates
+      ✔ should include @dotenvx/dotenvx in all templates
+      ✔ should include pm2 ecosystem in all templates
+      ✔ should replace {{name}} placeholder in package.json
+    printBanner()
+
+╔════════════════════════════════════════════════════════════════════╗
+║                     Create SKWeb Project                           ║
+╚════════════════════════════════════════════════════════════════════╝
+
+      ✔ should not throw
+    printSuccess()
+
+╔════════════════════════════════════════════════════════════════════╗
+║                         项目创建成功！                               ║
+╚════════════════════════════════════════════════════════════════════╝
+
+项目名称: my-app
+项目路径: /tmp/my-app/my-app
+
+接下来可以执行:
+
+  cd my-app
+
+  # 复制环境变量模板并按需修改
+  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 测试框架
+
+      ✔ should not throw
+
+
+  10 passing (179ms)
+

package/CHANGELOG.md

@@ -1,5 +1,54 @@
 # create-skweb
 
+## 3.2.0
+
+### Minor Changes
+
+- c5338b9: feat(templates): honor `--auth` option at generation time, not at runtime
+
+  Previously `app.js` / `app.ts` always contained both the static and jwks
+  JWT branches and decided which to use at runtime via `process.env.AUTH_PROVIDER`.
+  That meant the `--auth` CLI option was effectively a hint, not a real
+  choice: every generated project shipped both code paths and the
+  `AUTH_PROVIDER=...` line in `.env.example`, even projects that explicitly
+  chose static or jwks.
+
+  Now `createProject` reads the `auth` option and writes only the
+  matching files:
+
+  - `app.auth-static.{js,ts}` → `app.{js,ts}` (static only)
+  - `app.auth-jwks.{js,ts}` → `app.{js,ts}` (jwks only)
+  - `config.auth-static.{js,ts}` → `config.{js,ts}` (exports `checkJwtSecret`)
+  - `config.auth-jwks.{js,ts}` → `config.{js,ts}` (exports `checkOIDCConfig`)
+  - `swagger.auth-static.{js,ts}` → `swagger.{js,ts}` (HTTP bearer security)
+  - `swagger.auth-jwks.{js,ts}` → `swagger.{js,ts}` (OIDC openIdConnect)
+  - `.env.example.auth-static` → `.env.example` (JWT_SECRET only)
+  - `.env.example.auth-jwks` → `.env.example` (OIDC\_\* only)
+
+  Generated projects are now leaner: a static-only project contains no
+  JWKS code or env vars, and vice versa. The `checkJwtSecret` /
+  `checkOIDCConfig` split also keeps the JWT_SECRET default-value
+  warning from leaking into the cron worker process.
+
+## 3.1.2
+
+### Patch Changes
+
+- 03ebe56: refactor(templates): separate JWT secret validation from generic env check
+
+  `validateConfig` (in templates/cjs/mjs/ts `src/utils/config.{js,ts}`) no longer
+  warns about `JWT_SECRET` default value. The JWT-specific check is moved to a
+  new `checkJwtSecret()` helper that is now only invoked from the web bootstrap
+  (`src/app.{js,ts}`), not from `cronWorker.js` or CLI commands. This removes the
+  spurious "JWT_SECRET is using default value" warning in the cron worker
+  process, which never uses JWT.
+
+## 3.1.1
+
+### Patch Changes
+
+- update template versions
+
 ## 3.1.0
 
 ### Minor Changes

package/dist/cli.js

@@ -32,12 +32,30 @@ 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;
+            }
+        }
         let content = await fs.readFile(srcPath, 'utf-8');
         content = content
             .replace(/\{\{name\}\}/g, name)
             .replace(/\{\{description\}\}/g, description)
             .replace(/\{\{auth\}\}/g, auth);
-        const destPath = path.join(targetDir, fileName);
+        const destPath = path.join(targetDir, outputName);
         await fs.writeFile(destPath, content);
     }
     await fs.mkdirs(path.join(targetDir, 'logs'));

package/dist/index.js

@@ -27,12 +27,30 @@ 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;
+            }
+        }
         let content = await fs.readFile(srcPath, 'utf-8');
         content = content
             .replace(/\{\{name\}\}/g, name)
             .replace(/\{\{description\}\}/g, description)
             .replace(/\{\{auth\}\}/g, auth);
-        const destPath = path.join(targetDir, fileName);
+        const destPath = path.join(targetDir, outputName);
         await fs.writeFile(destPath, content);
     }
     await fs.mkdirs(path.join(targetDir, 'logs'));

package/package.json

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

package/src/index.ts

@@ -42,6 +42,24 @@ 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
+      }
+    }
+
     let content = await fs.readFile(srcPath, 'utf-8')
 
     content = content
@@ -49,7 +67,7 @@ export async function createProject(options: CreateOptions): Promise<void> {
       .replace(/\{\{description\}\}/g, description)
       .replace(/\{\{auth\}\}/g, auth)
 
-    const destPath = path.join(targetDir, fileName)
+    const destPath = path.join(targetDir, outputName)
     await fs.writeFile(destPath, content)
   }
 

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

@@ -38,23 +38,12 @@ REDIS_DB=0
 # (Production is always disabled to avoid exposing internal API details.)
 SWAGGER_ENABLED=true
 
-# ---------- Auth Provider ----------
-# 'static' (default): use a shared secret (HS256)
-# 'jwks': verify via JWKS endpoint (Keycloak / Auth0 / generic OIDC)
-AUTH_PROVIDER={{auth}}
-
-# ---------- JWT (static mode) ----------
-# [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
-
-# ---------- JWT (jwks mode, OIDC compatible) ----------
+# ---------- Auth: jwks (OIDC compatible) ----------
 # Works with any OIDC-compliant IdP. Common issuer formats:
 #   Keycloak:  https://kc.example.com/realms/myrealm
 #   Auth0:     https://your-tenant.auth0.com/
 #   Okta:      https://your-domain.okta.com/oauth2/default
 #   Authing:   https://your-app.authing.cn/oauth2/default
-#   Keycloak Realm: https://kc.example.com/auth/realms/myrealm
 # `audience` is the client id of this API in the IdP (recommended).
 # JWKS URI is auto-derived as ${OIDC_ISSUER}/.well-known/jwks.json
 # unless OIDC_JWKS_URI is set explicitly.

package/templates/cjs/.env.example.auth-static

@@ -0,0 +1,54 @@
+# ============================================
+# SKWeb Environment Variables Template
+# ============================================
+# Copy this file to .env and fill in your values:
+#   cp .env.example .env
+#
+# Variables with default values can be omitted.
+# Variables marked [REQUIRED] must be set in production.
+
+# ---------- Node Environment ----------
+# Development | Production | Test
+NODE_ENV=development
+
+# ---------- Server ----------
+PORT=3000
+HOST=0.0.0.0
+
+# ---------- Database (MySQL / MariaDB) ----------
+DB_HOST=127.0.0.1
+DB_PORT=3306
+DB_USER=root
+DB_PASS=
+DB_NAME={{name}}
+DB_DIALECT=mysql
+DB_CHARSET=utf8mb4
+DEBUG_DB=false
+
+# ---------- Redis ----------
+REDIS_HOST=127.0.0.1
+REDIS_PORT=6379
+REDIS_PASSWORD=
+REDIS_DB=0
+
+# ---------- Swagger / OpenAPI ----------
+# Mounts Swagger UI at /api-docs and exposes raw spec at /api-docs.json.
+# Only enabled when NODE_ENV is 'development' or 'test'.
+# Set SWAGGER_ENABLED=false to force-disable in dev/test as well.
+# (Production is always disabled to avoid exposing internal API details.)
+SWAGGER_ENABLED=true
+
+# ---------- 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
+
+# ---------- Logging ----------
+# error | warn | info | http | verbose | debug | silly
+LOG_LEVEL=info
+LOG_DIR=./logs
+LOG_CONSOLE=true
+
+# ---------- CORS ----------
+# Comma-separated origins, or * for all
+CORS_ORIGIN=*

package/templates/cjs/package.json

@@ -22,14 +22,14 @@
   "dependencies": {
     "@dotenvx/dotenvx": "^1.75.1",
     "http-errors": "^2.0.1",
-    "skweb-express": "^2.0.0",
+    "skweb-express": "^2.0.3",
     "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.0.0",
-    "skweb-plugin": "^2.0.0",
+    "skweb-framework": "^2.1.0",
+    "skweb-plugin": "^2.1.1",
     "skweb-util": "^2.0.0",
     "winston": "^3.19.0",
     "sequelize": "^6.37.8",

package/templates/cjs/src/app.auth-jwks.js

@@ -0,0 +1,131 @@
+require('dotenv/config')
+
+const path = require('path')
+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 { logger } = require('./utils/logger.js')
+const { checkRequiredEnv, checkOIDCConfig } = require('./utils/config.js')
+const { buildOpenApiSpec } = require('./swagger.js')
+
+/**
+ * JWT 配置（jwks 模式，通过 OIDC 兼容的 JWKS 端点验证 RS256 签名）。
+ */
+function buildJwtOptions() {
+  const issuer = process.env.OIDC_ISSUER
+  const jwksUri = process.env.OIDC_JWKS_URI
+  const audience = process.env.OIDC_AUDIENCE
+  if (!issuer && !jwksUri) {
+    throw new Error('jwks mode requires OIDC_ISSUER or OIDC_JWKS_URI')
+  }
+  return {
+    provider: 'jwks',
+    algorithms: ['RS256'],
+    jwks: { jwksUri, issuer, audience },
+    verify: { issuer, audience },
+    requestProperty: 'resolvedToken'
+  }
+}
+
+function shouldEnableSwagger() {
+  const env = (process.env.NODE_ENV || '').toLowerCase()
+  if (env !== 'development' && env !== 'test') return false
+  if ((process.env.SWAGGER_ENABLED || '').toLowerCase() === 'false') return false
+  return true
+}
+
+async function bootstrap() {
+  logger.info('[app] Initializing web process...')
+
+  if (!checkRequiredEnv()) {
+    logger.error('[app] Configuration validation failed, exiting...')
+    process.exit(1)
+  }
+  if (!checkOIDCConfig()) {
+    logger.error('[app] OIDC configuration validation failed, exiting...')
+    process.exit(1)
+  }
+
+  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({
+    modelsDir: path.join(__dirname, './models'),
+    controllersDir: path.join(__dirname, './controllers')
+  })
+
+  app.disable('x-powered-by')
+  app.disable('etag')
+
+  app.set('trust proxy', true)
+
+  app.set('wrap response', true)
+  app.setOkCode(0)
+  app.setOkMessage('success')
+
+  const jwtOptions = buildJwtOptions()
+  app.setJWT('default', jwtOptions)
+  app.setJwtHintHeader('JwtHint')
+
+  logger.info(`[app] JWT auth provider: jwks (issuer: ${jwtOptions.jwks.issuer || jwtOptions.jwks.jwksUri})`)
+
+  app.use(expressLogger())
+  app.use(express.static(path.join(__dirname, '..', 'public')))
+
+  if (shouldEnableSwagger()) {
+    const openapiSpec = buildOpenApiSpec()
+    app.get('/api-docs.json', (_req, res) => res.json(openapiSpec))
+    app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(openapiSpec, {
+      customSiteTitle: `${process.env.APP_NAME || 'SKWeb'} API Docs`,
+      swaggerOptions: { persistAuthorization: true }
+    }))
+    logger.info(`[app] Swagger UI mounted at http://localhost:${process.env.PORT || 3000}/api-docs (env: ${process.env.NODE_ENV})`)
+  } else {
+    logger.info(`[app] Swagger UI disabled (env: ${process.env.NODE_ENV || 'unset'})`)
+  }
+
+  await framework.loadControllers()
+
+  app.use(expressErrorHandler())
+
+  framework.start(Number(process.env.PORT) || 3000)
+
+  logger.info('[app] Initialization complete (web process)')
+
+  process.on('uncaughtException', (err) => {
+    logger.error(`[app] uncaughtException: ${err.stack || err.message}`)
+    process.exit(1)
+  })
+  process.on('unhandledRejection', (reason) => {
+    logger.error(`[app] unhandledRejection: ${reason instanceof Error ? reason.stack : String(reason)}`)
+    process.exit(1)
+  })
+}
+
+if (require.main === module) {
+  bootstrap().catch((err) => {
+    logger.error('[app] Fatal error:', err)
+    process.exit(1)
+  })
+}
+
+module.exports = { bootstrap }

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

@@ -1,42 +1,19 @@
 require('dotenv/config')
 
 const path = require('path')
-// skweb-express / skweb-express-logger 的 CJS 产物形态是
-// `{ default: fn, errorHandler, ... }`。直接 `require('skweb-express')` 拿到的是
-// 命名空间对象，`express()` 会 TypeError。这里走 .default。
 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 { logger } = require('./utils/logger.js')
-const { checkRequiredEnv } = require('./utils/config.js')
+const { checkRequiredEnv, checkJwtSecret } = require('./utils/config.js')
 const { buildOpenApiSpec } = require('./swagger.js')
 
 /**
- * 构建 JWT 配置，支持两种模式：
- *  - 'static' (默认)：使用共享密钥（HS256/HS384/HS512），适用于自签 token
- *  - 'jwks'：通过 JWKS 端点动态获取公钥（RS256 等），适用于 Keycloak/Auth0 等 IdP
+ * JWT 配置（static 模式，HS256 共享密钥）。
  */
 function buildJwtOptions() {
-  const provider = process.env.AUTH_PROVIDER || 'static'
-
-  if (provider === 'jwks') {
-    const issuer = process.env.OIDC_ISSUER
-    const jwksUri = process.env.OIDC_JWKS_URI
-    const audience = process.env.OIDC_AUDIENCE
-    if (!issuer && !jwksUri) {
-      throw new Error('AUTH_PROVIDER=jwks requires OIDC_ISSUER or OIDC_JWKS_URI')
-    }
-    return {
-      provider: 'jwks',
-      algorithms: ['RS256'],
-      jwks: { jwksUri, issuer, audience },
-      verify: { issuer, audience },
-      requestProperty: 'resolvedToken'
-    }
-  }
-
   return {
     provider: 'static',
     secret: process.env.JWT_SECRET || 'please-change-this-in-production',
@@ -64,6 +41,10 @@ async function bootstrap() {
     logger.error('[app] Configuration validation failed, exiting...')
     process.exit(1)
   }
+  if (!checkJwtSecret()) {
+    logger.error('[app] JWT configuration validation failed, exiting...')
+    process.exit(1)
+  }
 
   const framework = new WebFramework({
     db: {
@@ -99,21 +80,15 @@ async function bootstrap() {
   app.setOkCode(0)
   app.setOkMessage('success')
 
-  // JWT 配置（按 AUTH_PROVIDER 选择 static 或 jwks 模式）
   const jwtOptions = buildJwtOptions()
   app.setJWT('default', jwtOptions)
   app.setJwtHintHeader('JwtHint')
 
-  if (jwtOptions.provider === 'jwks') {
-    logger.info(`[app] JWT auth provider: jwks (issuer: ${jwtOptions.jwks.issuer || jwtOptions.jwks.jwksUri})`)
-  } else {
-    logger.info('[app] JWT auth provider: static (HS256)')
-  }
+  logger.info('[app] JWT auth provider: static (HS256)')
 
   app.use(expressLogger())
   app.use(express.static(path.join(__dirname, '..', 'public')))
 
-  // 仅在 dev / test 环境挂载 Swagger UI（默认关闭，需显式 SWAGGER_ENABLED=true）
   if (shouldEnableSwagger()) {
     const openapiSpec = buildOpenApiSpec()
     app.get('/api-docs.json', (_req, res) => res.json(openapiSpec))
@@ -128,14 +103,12 @@ async function bootstrap() {
 
   await framework.loadControllers()
 
-  // 错误日志中间件：挂在所有路由之后，记录业务错误并继续传递给默认错误处理。
   app.use(expressErrorHandler())
 
   framework.start(Number(process.env.PORT) || 3000)
 
   logger.info('[app] Initialization complete (web process)')
 
-  // 未捕获异常：打印堆栈后直接退出。OS / 进程管理器负责回收资源。
   process.on('uncaughtException', (err) => {
     logger.error(`[app] uncaughtException: ${err.stack || err.message}`)
     process.exit(1)

package/templates/cjs/src/swagger.auth-jwks.js

@@ -0,0 +1,38 @@
+'use strict'
+
+const path = require('path')
+const swaggerJSDoc = require('swagger-jsdoc')
+
+function buildOpenApiSpec() {
+  return swaggerJSDoc({
+    definition: {
+      openapi: '3.0.3',
+      info: {
+        title: process.env.APP_NAME || 'SKWeb API',
+        version: process.env.API_VERSION || '1.0.0',
+        description: process.env.APP_DESCRIPTION || 'SKWeb project API documentation',
+        contact: { name: 'API Support' }
+      },
+      servers: [
+        { url: `http://localhost:${process.env.PORT || 3000}`, description: 'Local development' }
+      ],
+      components: {
+        securitySchemes: {
+          oidcAuth: {
+            type: 'openIdConnect',
+            openIdConnectUrl: process.env.OIDC_JWKS_URI
+              ? process.env.OIDC_JWKS_URI.replace(/\/jwks\.json$/, '/.well-known/openid-configuration')
+              : (process.env.OIDC_ISSUER
+                  ? `${process.env.OIDC_ISSUER.replace(/\/$/, '')}/.well-known/openid-configuration`
+                  : undefined)
+          }
+        }
+      }
+    },
+    apis: [
+      path.join(__dirname, 'controllers', '*.js')
+    ]
+  })
+}
+
+module.exports = { buildOpenApiSpec }

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

@@ -3,22 +3,6 @@
 const path = require('path')
 const swaggerJSDoc = require('swagger-jsdoc')
 
-/**
- * 构建 OpenAPI 3.0 规范对象。
- *
- * 控制器中应使用 @swagger JSDoc 注释描述端点，例如：
- *
- *   /**
- *    * @swagger
- *    * /api/users:
- *    *   get:
- *    *     summary: 获取用户列表
- *    *     tags: [Users]
- *    *     responses:
- *    *       200:
- *    *         description: OK
- *    *\/
- */
 function buildOpenApiSpec() {
   return swaggerJSDoc({
     definition: {
@@ -37,8 +21,7 @@ function buildOpenApiSpec() {
           bearerAuth: {
             type: 'http',
             scheme: 'bearer',
-            bearerFormat: 'JWT',
-            description: 'Paste a JWT token here (only needed when AUTH_PROVIDER=static)'
+            bearerFormat: 'JWT'
           }
         }
       }