birc-generator 0.9.0 → 1.0.0

package/lib/features.js

@@ -0,0 +1,558 @@
+const fs = require('fs');
+const path = require('path');
+const VERSIONS = require('../versions');
+const {
+  randomDbPassword,
+  loadProjectConfig,
+  inferProjectNameKebab,
+  resolvePersistence,
+  projectRoot,
+  YML_ANCHOR,
+  GRADLE_ANCHOR,
+  GRADLE_PLUGIN_ANCHOR,
+  GRADLE_ALLPROJECTS_ANCHOR,
+  requireGradleAnchor,
+  gradleAnchorPattern
+} = require('./project');
+
+function uniqueFeatureKeys(features) {
+  return [...new Set((features || []).filter((featureKey) => FEATURES[featureKey]))];
+}
+
+function isAddForce(data) {
+  return Boolean(data && data.force) || process.env.BIRC_ADD_FORCE === '1';
+}
+
+function isAddSync(data) {
+  return Boolean(data && data.sync) || process.env.BIRC_ADD_SYNC === '1';
+}
+
+function preflightAdd(featureKeys, { destBase, ymlPath, gradlePath }) {
+  const errors = [];
+  for (const featureKey of featureKeys) {
+    const feature = FEATURES[featureKey];
+    if (feature.ymlBlock) {
+      const target = path.resolve(destBase, ymlPath);
+      if (!fs.existsSync(target)) {
+        errors.push(`${featureKey}: 找不到 ${ymlPath}`);
+      } else if (!fs.readFileSync(target, 'utf8').includes(YML_ANCHOR)) {
+        errors.push(`${featureKey}: ${ymlPath} 沒有 ${YML_ANCHOR}`);
+      }
+    }
+    if (feature.gradleDep) {
+      requireGradleAnchor(errors, featureKey, destBase, gradlePath, GRADLE_ANCHOR);
+    }
+    if (feature.gradlePlugin) {
+      requireGradleAnchor(errors, featureKey, destBase, gradlePath, GRADLE_PLUGIN_ANCHOR);
+    }
+    if (feature.gradleAllprojects) {
+      requireGradleAnchor(errors, featureKey, destBase, gradlePath, GRADLE_ALLPROJECTS_ANCHOR);
+    }
+  }
+  if (errors.length > 0) {
+    throw new Error(`add 預檢查失敗，沒有寫任何檔：\n${errors.map((line) => `  ${line}`).join('\n')}`);
+  }
+}
+
+function buildAddActions(data) {
+  const force = isAddForce(data);
+  const syncAll = isAddSync(data);
+  const config = loadProjectConfig();
+  const installed = new Set(config.features || []);
+  const selected = syncAll
+    ? uniqueFeatureKeys(config.features)
+    : uniqueFeatureKeys(data.features);
+  const featuresToAdd = selected.filter((featureKey) => force || syncAll || !installed.has(featureKey));
+  if (featuresToAdd.length === 0) {
+    return [];
+  }
+
+  const basePackage = config.basePackage;
+  const basePackagePath = basePackage.replace(/\./g, '/');
+  const srcPath = config.srcPath || 'src/main/java';
+  const resourcesPath = config.resourcesPath || 'src/main/resources';
+  const ymlPath = config.applicationYmlPath || `${resourcesPath}/application.yml`;
+  const gradlePath = config.buildGradlePath || 'build.gradle';
+  const root = `${srcPath}/${basePackagePath}`;
+  const testRoot = `${config.testSrcPath || 'src/test/java'}/${basePackagePath}`;
+  const persistence = resolvePersistence(config);
+  const destBase = projectRoot();
+
+  preflightAdd(featuresToAdd, { destBase, ymlPath, gradlePath });
+
+  const templateData = {
+    ...VERSIONS,
+    basePackage,
+    projectName: config.projectNameKebab || inferProjectNameKebab(config),
+    projectNameKebab: config.projectNameKebab || inferProjectNameKebab(config),
+    gitlabProjectPath: data.gitlabProjectPath || '',
+    dbRootPassword: randomDbPassword(),
+    dbPassword: randomDbPassword(),
+    entityPackage: persistence.entityPackage,
+    daoPackage: persistence.daoPackage
+  };
+
+  let actions = [];
+  for (const featureKey of featuresToAdd) {
+    const reinstall = installed.has(featureKey);
+    actions = actions.concat(
+      featureActions(featureKey, {
+        root,
+        testRoot,
+        entityRoot: persistence.entityRoot,
+        daoRoot: persistence.daoRoot,
+        resourcesRoot: resourcesPath,
+        projectRoot: '.',
+        ymlPath,
+        gradlePath,
+        templateData,
+        overwriteFiles: force || syncAll,
+        skipConfigFragments: reinstall && (force || syncAll)
+      })
+    );
+  }
+
+  actions.push({ type: 'updateProjectFeatures', features: featuresToAdd });
+  return actions;
+}
+
+// 每個 feature 對應：要加哪些檔案、要往 application.yml / build.gradle 的哪個 anchor 插入什麼
+const FEATURES = {
+  email: {
+    label: 'Email（JavaMailSender + Thymeleaf 模板）',
+    files: [
+      { templateFile: 'templates/email/EmailService.hbs', dest: 'service/EmailService.java' },
+      { templateFile: 'templates/email/EmailServiceImpl.hbs', dest: 'service/impl/EmailServiceImpl.java' },
+      { templateFile: 'templates/email/EmailAsyncConfig.hbs', dest: 'config/EmailAsyncConfig.java' }
+    ],
+    resourceFiles: [
+      { templateFile: 'templates/email/sample-template.hbs', dest: 'email/sample.html' }
+    ],
+    ymlBlock: 'templates/email/application-yml-block.hbs',
+    gradleDep: 'templates/email/build-gradle-dep.hbs'
+  },
+  auth: {
+    label: '帳號登入（auth_users 表 + JWT，POST /api/auth/login 回 X-Auth-Token）',
+    files: [
+      { templateFile: 'templates/auth/JwtProperties.hbs', dest: 'config/JwtProperties.java' },
+      { templateFile: 'templates/auth/AuthSecurityCustomizer.hbs', dest: 'config/AuthSecurityCustomizer.java' },
+      { templateFile: 'templates/auth/JwtSecretEnvironmentPostProcessor.hbs', dest: 'config/JwtSecretEnvironmentPostProcessor.java' },
+      { templateFile: 'templates/auth/JwtService.hbs', dest: 'security/JwtService.java' },
+      { templateFile: 'templates/auth/JwtAuthenticationFilter.hbs', dest: 'security/JwtAuthenticationFilter.java' },
+      { templateFile: 'templates/auth/JpaUserDetailsService.hbs', dest: 'security/JpaUserDetailsService.java' },
+      { templateFile: 'templates/auth/LoginRequest.hbs', dest: 'dto/LoginRequest.java' },
+      { templateFile: 'templates/auth/AuthController.hbs', dest: 'controller/AuthController.java' },
+      { templateFile: 'templates/auth/LoginFailedException.hbs', dest: 'exception/LoginFailedException.java' }
+    ],
+    entityFiles: [{ templateFile: 'templates/auth/AuthUser.hbs', dest: 'AuthUser.java' }],
+    daoFiles: [{ templateFile: 'templates/auth/AuthUserDAO.hbs', dest: 'AuthUserDAO.java' }],
+    testFiles: [
+      { templateFile: 'templates/auth/AuthFlowTest.hbs', dest: 'AuthFlowTest.java' },
+      { templateFile: 'templates/auth/JwtSecretEnvTest.hbs', dest: 'JwtSecretEnvTest.java' }
+    ],
+    resourceFiles: [
+      { templateFile: 'templates/auth/V1__create_auth_users_table.sql.hbs', dest: 'db/migration/V1__create_auth_users_table.sql' },
+      { templateFile: 'templates/auth/spring.factories.hbs', dest: 'META-INF/spring.factories' }
+    ],
+    ymlBlock: 'templates/auth/application-yml-block.hbs',
+    gradleDep: 'templates/auth/build-gradle-dep.hbs'
+  },
+
+  sso: {
+    label: 'SSO（只有設定骨架，驗票與發證要自己接）',
+    files: [
+      { templateFile: 'templates/sso/SsoProperties.hbs', dest: 'security/SsoProperties.java' },
+      { templateFile: 'templates/sso/SsoAutoConfiguration.hbs', dest: 'config/SsoAutoConfiguration.java' }
+    ],
+    resourceFiles: [],
+    ymlBlock: 'templates/sso/application-yml-block.hbs',
+    gradleDep: null
+  },
+  oauth: {
+    label: 'OAuth2 登入（範例接 Google，success handler 要自己掛 SecurityCustomizer）',
+    files: [
+      { templateFile: 'templates/oauth/OAuth2LoginSuccessHandler.hbs', dest: 'config/OAuth2LoginSuccessHandler.java' }
+    ],
+    resourceFiles: [],
+    ymlBlock: 'templates/oauth/application-yml-block.hbs',
+    gradleDep: 'templates/oauth/build-gradle-dep.hbs'
+  },
+  scheduling: {
+    label: '排程（Scheduling Tasks，@EnableScheduling + 範例 Job）',
+    files: [
+      { templateFile: 'templates/scheduling/SchedulingConfig.hbs', dest: 'config/SchedulingConfig.java' },
+      { templateFile: 'templates/scheduling/SampleSchedule.hbs', dest: 'schedule/SampleSchedule.java' }
+    ],
+    resourceFiles: [],
+    ymlBlock: 'templates/scheduling/application-yml-block.hbs',
+    gradleDep: null
+  },
+  aop: {
+    label: 'AOP 事件記錄（自訂 @OperationLog 註解 + Aspect）',
+    files: [
+      { templateFile: 'templates/aop/OperationLog.hbs', dest: 'annotation/OperationLog.java' },
+      { templateFile: 'templates/aop/OperationLogAspect.hbs', dest: 'aspect/OperationLogAspect.java' }
+    ],
+    resourceFiles: [],
+    ymlBlock: null,
+    gradleDep: 'templates/aop/build-gradle-dep.hbs'
+  },
+  client: {
+    label: 'Client（呼叫外部 API 的 RestClient 封裝）',
+    files: [
+      { templateFile: 'templates/client/ExternalApiProperties.hbs', dest: 'config/ExternalApiProperties.java' },
+      { templateFile: 'templates/client/ExternalApiClientConfig.hbs', dest: 'config/ExternalApiClientConfig.java' },
+      { templateFile: 'templates/client/ExternalApiClient.hbs', dest: 'client/ExternalApiClient.java' }
+    ],
+    resourceFiles: [],
+    ymlBlock: 'templates/client/application-yml-block.hbs',
+    gradleDep: null
+  },
+  clockin: {
+    label: '簽到（接中心簽到系統 BIRC CMS 的 API）',
+    files: [
+      { templateFile: 'templates/clockin/ClockInProperties.hbs', dest: 'config/ClockInProperties.java' },
+      { templateFile: 'templates/clockin/ClockInClientConfig.hbs', dest: 'config/ClockInClientConfig.java' },
+      { templateFile: 'templates/clockin/ClockInClient.hbs', dest: 'client/ClockInClient.java' },
+      { templateFile: 'templates/clockin/ClockInApiResponse.hbs', dest: 'dto/clockin/ClockInApiResponse.java' },
+      { templateFile: 'templates/clockin/ClockInRecord.hbs', dest: 'dto/clockin/ClockInRecord.java' },
+      { templateFile: 'templates/clockin/ClockInPage.hbs', dest: 'dto/clockin/ClockInPage.java' },
+      { templateFile: 'templates/clockin/UnclockedMember.hbs', dest: 'dto/clockin/UnclockedMember.java' },
+      { templateFile: 'templates/clockin/UserPermission.hbs', dest: 'dto/clockin/UserPermission.java' },
+      { templateFile: 'templates/clockin/OnDutyWeek.hbs', dest: 'dto/clockin/OnDutyWeek.java' },
+      { templateFile: 'templates/clockin/MemberImage.hbs', dest: 'dto/clockin/MemberImage.java' },
+      {
+        templateFile: 'templates/clockin/ClockInApiException.hbs',
+        dest: 'exception/clockin/ClockInApiException.java'
+      },
+      { templateFile: 'templates/clockin/ClockInController.hbs', dest: 'controller/ClockInController.java' }
+    ],
+    resourceFiles: [],
+    ymlBlock: 'templates/clockin/application-yml-block.hbs',
+    gradleDep: null
+  },
+  sentry: {
+    label: 'Sentry（錯誤追蹤 + 客戶端例外過濾）',
+    files: [
+      { templateFile: 'templates/sentry/SentryConfig.hbs', dest: 'config/SentryConfig.java' }
+    ],
+    resourceFiles: [],
+    ymlBlock: 'templates/sentry/application-yml-block.hbs',
+    gradleDep: 'templates/sentry/build-gradle-dep.hbs'
+  },
+  log4j2: {
+    label: 'Log4j2（主控台 + rolling file + MDC）',
+    files: [],
+    resourceFiles: [
+      { templateFile: 'templates/log4j2/log4j2-spring.xml.hbs', dest: 'log4j2-spring.xml' }
+    ],
+    ymlBlock: null,
+    gradleDep: 'templates/log4j2/build-gradle-dep.hbs'
+  },
+  openapi: {
+    label: 'OpenAPI（springdoc + Swagger UI + Bearer JWT）',
+    files: [
+      { templateFile: 'templates/openapi/OpenApiConfig.hbs', dest: 'config/OpenApiConfig.java' }
+    ],
+    testFiles: [
+      { templateFile: 'templates/openapi/ApiDocsAccessTest.hbs', dest: 'ApiDocsAccessTest.java' }
+    ],
+    resourceFiles: [],
+    ymlBlock: 'templates/openapi/application-yml-block.hbs',
+    gradleDep: 'templates/openapi/build-gradle-dep.hbs'
+  },
+  fileUpload: {
+    label: '檔案上傳（本機磁碟儲存，可自行改接 S3 / MinIO）',
+    files: [
+      { templateFile: 'templates/file-upload/FileStorageProperties.hbs', dest: 'config/FileStorageProperties.java' },
+      { templateFile: 'templates/file-upload/FileStorageService.hbs', dest: 'service/FileStorageService.java' },
+      { templateFile: 'templates/file-upload/FileStorageServiceImpl.hbs', dest: 'service/impl/FileStorageServiceImpl.java' },
+      { templateFile: 'templates/file-upload/FileUploadController.hbs', dest: 'controller/FileUploadController.java' },
+      { templateFile: 'templates/file-upload/FileUtils.hbs', dest: 'util/file/FileUtils.java' },
+      { templateFile: 'templates/file-upload/FileExtensionUtils.hbs', dest: 'util/file/FileExtensionUtils.java' },
+      { templateFile: 'templates/file-upload/EmptyFileException.hbs', dest: 'exception/file/EmptyFileException.java' },
+      { templateFile: 'templates/file-upload/FileExtensionIllegalException.hbs', dest: 'exception/file/FileExtensionIllegalException.java' },
+      { templateFile: 'templates/file-upload/InvalidStoredFileException.hbs', dest: 'exception/file/InvalidStoredFileException.java' },
+      { templateFile: 'templates/file-upload/FileTooLargeException.hbs', dest: 'exception/file/FileTooLargeException.java' }
+    ],
+    testFiles: [
+      { templateFile: 'templates/file-upload/FileExtensionUtilsTest.hbs', dest: 'util/file/FileExtensionUtilsTest.java' }
+    ],
+    resourceFiles: [],
+    ymlBlock: 'templates/file-upload/application-yml-block.hbs',
+    gradleDep: null
+  },
+  pagination: {
+    label: '分頁查詢（Specification 動態條件 + PageRequest/PageResponse）',
+    files: [
+      { templateFile: 'templates/pagination/SearchCriteria.hbs', dest: 'specification/SearchCriteria.java' },
+      { templateFile: 'templates/pagination/GenericSpecification.hbs', dest: 'specification/GenericSpecification.java' },
+      { templateFile: 'templates/pagination/SpecificationSupport.hbs', dest: 'specification/SpecificationSupport.java' },
+      { templateFile: 'templates/pagination/PageRequest.hbs', dest: 'dto/PageRequest.java' },
+      { templateFile: 'templates/pagination/PageResponse.hbs', dest: 'dto/PageResponse.java' },
+      { templateFile: 'templates/pagination/Pager.hbs', dest: 'dto/Pager.java' },
+      { templateFile: 'templates/pagination/PageInfo.hbs', dest: 'dto/PageInfo.java' }
+    ],
+    resourceFiles: [],
+    ymlBlock: null,
+    gradleDep: null
+  },
+  validGroup: {
+    label: '驗證群組（ValidGroup：Create / Update / Delete / Submit）',
+    files: [
+      { templateFile: 'templates/valid-group/ValidGroup.hbs', dest: 'validation/ValidGroup.java' }
+    ],
+    resourceFiles: [],
+    ymlBlock: null,
+    gradleDep: null
+  },
+  permission: {
+    label: '權限控管（@RequirePermission，需搭配帳號登入或自己的登入機制）',
+    files: [
+      { templateFile: 'templates/permission/RequirePermission.hbs', dest: 'annotation/RequirePermission.java' },
+      { templateFile: 'templates/permission/PermissionAspect.hbs', dest: 'aspect/PermissionAspect.java' }
+    ],
+    resourceFiles: [],
+    ymlBlock: null,
+    gradleDep: 'templates/permission/build-gradle-dep.hbs'
+  },
+  gitlabCi: {
+    label: '.gitlab-ci.yml（Harbor build/push + SSH deploy，對齊 teaching-platform）',
+    files: [],
+    resourceFiles: [],
+    rootFiles: [
+      { templateFile: 'templates/gitlab-ci/gitlab-ci.hbs', dest: '.gitlab-ci.yml' }
+    ],
+    ymlBlock: null,
+    gradleDep: null
+  },
+  docker: {
+    label: 'Docker（多階段 Dockerfile + compose + .env.example）',
+    files: [],
+    resourceFiles: [],
+    rootFiles: [
+      { templateFile: 'templates/docker/Dockerfile.hbs', dest: 'Dockerfile' },
+      { templateFile: 'templates/docker/docker-compose.yml.hbs', dest: 'docker-compose.yml' },
+      { templateFile: 'templates/docker/docker-compose.prod.yml.hbs', dest: 'docker-compose.prod.yml' },
+      { templateFile: 'templates/docker/env.example.hbs', dest: '.env.example' },
+      { templateFile: 'templates/docker/dockerignore.hbs', dest: '.dockerignore' }
+    ],
+    ymlBlock: null,
+    gradleDep: null
+  },
+  spotless: {
+    label: 'Spotless（Eclipse 4.31 格式化，commit 前 ./gradlew spotlessApply）',
+    files: [],
+    resourceFiles: [],
+    rootFiles: [
+      { templateFile: 'templates/spotless/spotless_formatter.xml', dest: 'spotless_formatter.xml' }
+    ],
+    ymlBlock: null,
+    gradleDep: null,
+    gradlePlugin: 'templates/spotless/build-gradle-plugin.hbs',
+    gradleAllprojects: 'templates/spotless/build-gradle-allprojects.hbs'
+  }
+};
+
+const FEATURE_GROUPS = [
+  {
+    title: '常用',
+    keys: [
+      'docker',
+      'log4j2',
+      'openapi',
+      'spotless',
+      'validGroup',
+      'pagination',
+      'fileUpload',
+      'email',
+      'client',
+      'clockin',
+      'aop'
+    ]
+  },
+  { title: '登入', keys: ['auth', 'sso', 'oauth', 'permission'] },
+  { title: '營運', keys: ['gitlabCi', 'sentry', 'scheduling'] }
+];
+const DEFAULT_FEATURES = new Set(['docker', 'log4j2', 'validGroup', 'spotless']);
+
+function groupedFeatureChoices({
+  installed = new Set(),
+  allowInstalled = false,
+  withDefaults = false
+} = {}) {
+  const used = new Set();
+  const choices = [];
+  for (const group of FEATURE_GROUPS) {
+    const keys = group.keys.filter((key) => FEATURES[key]);
+    if (keys.length === 0) continue;
+    choices.push({ type: 'separator', line: `── ${group.title} ──` });
+    for (const key of keys) {
+      used.add(key);
+      choices.push({
+        name: FEATURES[key].label,
+        value: key,
+        checked: withDefaults && DEFAULT_FEATURES.has(key),
+        disabled: !allowInstalled && installed.has(key) ? '已安裝' : false
+      });
+    }
+  }
+  const leftover = Object.keys(FEATURES).filter((key) => !used.has(key));
+  if (leftover.length > 0) {
+    choices.push({ type: 'separator', line: '── 其他 ──' });
+    for (const key of leftover) {
+      choices.push({
+        name: FEATURES[key].label,
+        value: key,
+        checked: withDefaults && DEFAULT_FEATURES.has(key),
+        disabled: !allowInstalled && installed.has(key) ? '已安裝' : false
+      });
+    }
+  }
+  return choices;
+}
+
+// 產生單一 feature 的 plop actions。root / resourcesRoot / ymlPath / gradlePath 都是絕對相對於
+// plop destBasePath 的路徑，create 跟 add 共用同一份邏輯，差別只在 root 前面有沒有專案資料夾。
+function featureActions(featureKey, {
+  root,
+  testRoot,
+  entityRoot,
+  daoRoot,
+  resourcesRoot,
+  projectRoot,
+  ymlPath,
+  gradlePath,
+  templateData,
+  overwriteFiles = false,
+  skipConfigFragments = false
+}) {
+  const feature = FEATURES[featureKey];
+  if (!feature) {
+    throw new Error(`未知的 feature: ${featureKey}`);
+  }
+  const actions = [];
+
+  for (const f of feature.files) {
+    actions.push({
+      type: 'add',
+      path: `${root}/${f.dest}`,
+      templateFile: f.templateFile,
+      data: templateData,
+      skipIfExists: !overwriteFiles,
+      abortOnFail: true
+    });
+  }
+
+  for (const f of feature.testFiles || []) {
+    actions.push({
+      type: 'add',
+      path: `${testRoot}/${f.dest}`,
+      templateFile: f.templateFile,
+      data: templateData,
+      skipIfExists: !overwriteFiles,
+      abortOnFail: true
+    });
+  }
+
+  // Entity / DAO 不跟其它 Java 檔同一個 root：多模組時它們落在 databaseconfig 模組。
+  const persistenceFiles = [
+    [feature.entityFiles, entityRoot],
+    [feature.daoFiles, daoRoot]
+  ];
+  for (const [files, persistenceRoot] of persistenceFiles) {
+    for (const f of files || []) {
+      actions.push({
+        type: 'add',
+        path: `${persistenceRoot}/${f.dest}`,
+        templateFile: f.templateFile,
+        data: templateData,
+        skipIfExists: !overwriteFiles,
+        abortOnFail: true
+      });
+    }
+  }
+
+  for (const f of feature.resourceFiles) {
+    actions.push({
+      type: 'add',
+      path: `${resourcesRoot}/${f.dest}`,
+      templateFile: f.templateFile,
+      data: templateData,
+      skipIfExists: !overwriteFiles,
+      abortOnFail: true
+    });
+  }
+
+  // rootFiles：不屬於任何 package、也不進 resources 的檔案（.gitlab-ci.yml、Dockerfile 之類），
+  // 直接放到專案根目錄（create 是新資料夾根目錄，add 是目前目錄）。
+  if (feature.rootFiles) {
+    for (const f of feature.rootFiles) {
+      actions.push({
+        type: 'add',
+        path: `${projectRoot}/${f.dest}`,
+        templateFile: f.templateFile,
+        data: templateData,
+        skipIfExists: !overwriteFiles,
+        abortOnFail: true
+      });
+    }
+  }
+
+  if (feature.ymlBlock && !skipConfigFragments) {
+    actions.push({
+      type: 'appendFragment',
+      path: ymlPath,
+      pattern: new RegExp(`${YML_ANCHOR.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\n`),
+      templateFile: feature.ymlBlock,
+      data: templateData,
+      marker: featureKey,
+      commentToken: '#',
+      abortOnFail: true
+    });
+  }
+
+  // 同一個 feature 可能同時插 dependencies / plugins / allprojects 三處，marker 要分得開。
+  const gradleFragments = [
+    [feature.gradleDep, GRADLE_ANCHOR, featureKey],
+    [feature.gradlePlugin, GRADLE_PLUGIN_ANCHOR, `${featureKey}-plugin`],
+    [feature.gradleAllprojects, GRADLE_ALLPROJECTS_ANCHOR, `${featureKey}-allprojects`]
+  ];
+  for (const [templateFile, anchor, marker] of gradleFragments) {
+    if (templateFile && !skipConfigFragments) {
+      actions.push({
+        type: 'appendFragment',
+        path: gradlePath,
+        pattern: gradleAnchorPattern(anchor),
+        templateFile,
+        data: templateData,
+        marker,
+        commentToken: '//',
+        abortOnFail: true
+      });
+    }
+  }
+
+  // auth 的簽章金鑰只寫 .env（gitignore），不寫進 .env.example。
+  // 已有值不改，sync / add --force 也不該換一把新鑰匙。
+  if (featureKey === 'auth') {
+    actions.push({
+      type: 'ensureJwtSecret',
+      path: `${projectRoot}/.env`
+    });
+  }
+
+  return actions;
+}
+
+module.exports = {
+  FEATURES,
+  FEATURE_GROUPS,
+  DEFAULT_FEATURES,
+  uniqueFeatureKeys,
+  isAddForce,
+  isAddSync,
+  groupedFeatureChoices,
+  featureActions,
+  buildAddActions
+};