birc-generator 0.5.5

package/templates/spotless/build-gradle-allprojects.hbs

@@ -0,0 +1,16 @@
+    apply plugin: 'com.diffplug.spotless'
+
+    spotless {
+        java {
+            target 'src/main/java/**/controller/*.java',
+                   'src/main/java/**/service/**/*.java',
+                   'modules/**/src/main/java/**/entity/**/*.java',
+                   'modules/**/src/main/java/**/dao/*.java'
+
+            targetExclude 'build/**'
+            eclipse('4.31').configFile(rootProject.file('spotless_formatter.xml'))
+            removeUnusedImports()
+            trimTrailingWhitespace()
+            endWithNewline()
+        }
+    }

package/templates/spotless/build-gradle-plugin.hbs

@@ -0,0 +1 @@
+    id 'com.diffplug.spotless' version '{{spotlessVersion}}'

package/templates/spotless/spotless_formatter.xml

@@ -0,0 +1,83 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<profiles version="23">
+    <profile name="CustomFormatter">
+        <!-- ========== Indentation ========== -->
+        <setting id="org.eclipse.jdt.core.formatter.tabulation.char" value="space"/>
+        <setting id="org.eclipse.jdt.core.formatter.tabulation.size" value="4"/>
+        <setting id="org.eclipse.jdt.core.formatter.indentation.size" value="4"/>
+
+        <!-- ========== Line Width ========== -->
+        <setting id="org.eclipse.jdt.core.formatter.lineSplit" value="120"/>
+
+        <!-- ========== Braces (same line) ========== -->
+        <setting id="org.eclipse.jdt.core.formatter.brace_position_for_method_declaration" value="end_of_line"/>
+        <setting id="org.eclipse.jdt.core.formatter.brace_position_for_type_declaration" value="end_of_line"/>
+        <setting id="org.eclipse.jdt.core.formatter.brace_position_for_block" value="end_of_line"/>
+        <setting id="org.eclipse.jdt.core.formatter.brace_position_for_constructor_declaration" value="end_of_line"/>
+        <setting id="org.eclipse.jdt.core.formatter.brace_position_for_annotation_type_declaration" value="end_of_line"/>
+        <setting id="org.eclipse.jdt.core.formatter.brace_position_for_switch" value="end_of_line"/>
+        <setting id="org.eclipse.jdt.core.formatter.brace_position_for_lambda_body" value="end_of_line"/>
+
+        <!-- ========== Single-line control ========== -->
+        <setting id="org.eclipse.jdt.core.formatter.put_empty_statement_on_new_line" value="false"/>
+        <setting id="org.eclipse.jdt.core.formatter.keep_simple_if_on_one_line" value="true"/>
+        <setting id="org.eclipse.jdt.core.formatter.keep_then_statement_on_same_line" value="true"/>
+        <setting id="org.eclipse.jdt.core.formatter.keep_else_statement_on_same_line" value="true"/>
+
+        <!-- ========== Preserve line breaks in method chains ========== -->
+        <setting id="org.eclipse.jdt.core.formatter.join_wrapped_lines" value="false"/>
+
+        <!-- ========== Annotations on separate line ========== -->
+        <setting id="org.eclipse.jdt.core.formatter.insert_new_line_before_annotation_on_type" value="insert"/>
+        <setting id="org.eclipse.jdt.core.formatter.insert_new_line_before_annotation_on_method" value="insert"/>
+        <setting id="org.eclipse.jdt.core.formatter.insert_new_line_before_annotation_on_field" value="insert"/>
+        <setting id="org.eclipse.jdt.core.formatter.insert_new_line_before_annotation_on_local_variable" value="insert"/>
+        <setting id="org.eclipse.jdt.core.formatter.insert_new_line_before_annotation_on_parameter" value="do not insert"/>
+        <setting id="org.eclipse.jdt.core.formatter.insert_new_line_before_annotation_on_enum_constant" value="do not insert"/>
+
+        <!-- ========== Annotation content alignment (NO WRAP) ========== -->
+        <!-- This is the key setting: keeps @Content(...), @ExampleObject(value = ...) on same line -->
+        <setting id="org.eclipse.jdt.core.formatter.alignment_for_annotations_in_allocation_expression" value="0"/>
+        <setting id="org.eclipse.jdt.core.formatter.alignment_for_arguments_in_annotation" value="0"/>
+
+        <!-- ========== Blank lines ========== -->
+        <setting id="org.eclipse.jdt.core.formatter.blank_lines_before_package" value="0"/>
+        <setting id="org.eclipse.jdt.core.formatter.blank_lines_after_package" value="1"/>
+        <setting id="org.eclipse.jdt.core.formatter.blank_lines_before_first_class_body_declaration" value="1"/>
+        <setting id="org.eclipse.jdt.core.formatter.blank_lines_before_new_chunk" value="1"/>
+        <setting id="org.eclipse.jdt.core.formatter.blank_lines_before_member_type" value="1"/>
+
+        <!-- ========== Newlines ========== -->
+        <setting id="org.eclipse.jdt.core.formatter.line_terminator" value="LF"/>
+        <setting id="org.eclipse.jdt.core.formatter.insert_new_line_after_opening_brace" value="insert"/>
+        <setting id="org.eclipse.jdt.core.formatter.insert_new_line_before_catch" value="insert"/>
+        <setting id="org.eclipse.jdt.core.formatter.insert_new_line_before_else" value="insert"/>
+        <setting id="org.eclipse.jdt.core.formatter.insert_new_line_before_finally" value="insert"/>
+        <setting id="org.eclipse.jdt.core.formatter.insert_new_line_after_label" value="insert"/>
+
+        <!-- ========== Import organization ========== -->
+        <setting id="org.eclipse.jdt.core.formatter.import_order" value="java;javax;org;com;"/>
+        <setting id="org.eclipse.jdt.core.formatter.use_on_off_tags" value="true"/>
+        <setting id="org.eclipse.jdt.core.formatter.remove_unused_imports" value="true"/>
+
+        <!-- ========== Static imports ========== -->
+        <setting id="org.eclipse.jdt.core.formatter.static_import_order" value="org.junit.Assert;org.junit.Assume;org.junit.jupiter.api.Assertions;org.junit.jupiter.api.Assumptions;org.hamcrest.CoreMatchers;org.hamcrest.Matchers;"/>
+
+        <!-- ========== Alignment ========== -->
+        <setting id="org.eclipse.jdt.core.formatter.alignment_for_arguments_in_method_invocation" value="16"/>
+        <setting id="org.eclipse.jdt.core.formatter.alignment_for_parameters_in_method_declaration" value="16"/>
+        <setting id="org.eclipse.jdt.core.formatter.alignment_for_assignment" value="16"/>
+        <setting id="org.eclipse.jdt.core.formatter.alignment_for_conditional_expression" value="80"/>
+
+        <!-- ========== Wrapping ========== -->
+        <setting id="org.eclipse.jdt.core.formatter.wrapping_strategy_for_method_declaration" value="preserve_existing"/>
+
+        <!-- ========== Misc ========== -->
+        <setting id="org.eclipse.jdt.core.formatter.indent_empty_lines" value="false"/>
+        <setting id="org.eclipse.jdt.core.formatter.remove_trailing_whitespace_on_save" value="true"/>
+
+        <!-- ========== On/off tags ========== -->
+        <setting id="org.eclipse.jdt.core.formatter.disabling_tag" value="@formatter:off"/>
+        <setting id="org.eclipse.jdt.core.formatter.enabling_tag" value="@formatter:on"/>
+    </profile>
+</profiles>

package/templates/sso/SsoAutoConfiguration.hbs

@@ -0,0 +1,17 @@
+package {{basePackage}}.config;
+
+import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
+import org.springframework.boot.context.properties.EnableConfigurationProperties;
+import org.springframework.context.annotation.Configuration;
+import {{basePackage}}.security.SsoProperties;
+
+/**
+ * 只有在 application.yml 設 birc.sso.enabled=true 時才會載入。
+ * 目前先放設定骨架，實際打 SSO 驗證票根的邏輯（filter / interceptor）
+ * 依各專案的 SSO 供應商再補，直接寫在這個專案裡就好。
+ */
+@Configuration
+@ConditionalOnProperty(prefix = "birc.sso", name = "enabled", havingValue = "true")
+@EnableConfigurationProperties(SsoProperties.class)
+public class SsoAutoConfiguration {
+}

package/templates/sso/SsoProperties.hbs

@@ -0,0 +1,27 @@
+package {{basePackage}}.security;
+
+import jakarta.validation.constraints.NotBlank;
+import lombok.Getter;
+import lombok.Setter;
+import org.springframework.boot.context.properties.ConfigurationProperties;
+import org.springframework.validation.annotation.Validated;
+
+/**
+ * 校內 SSO 的設定，對應 application.yml 的 birc.sso.*。
+ * yml 開 enabled: true 並填 loginUrl / validateUrl 後，SsoAutoConfiguration 才會生效；
+ * 沒有 SSO 的專案不用理這段。enabled 時 URL 空白會在啟動失敗，不要拖到打 SSO 才發現。
+ */
+@Getter
+@Setter
+@Validated
+@ConfigurationProperties(prefix = "birc.sso")
+public class SsoProperties {
+
+    private boolean enabled = false;
+
+    @NotBlank
+    private String loginUrl;
+
+    @NotBlank
+    private String validateUrl;
+}

package/templates/sso/application-yml-block.hbs

@@ -0,0 +1,7 @@
+---
+# --- sso（由 birc-generator add 產生，啟用專案內的 SsoAutoConfiguration） ---
+birc:
+  sso:
+    enabled: true
+    login-url: ${SSO_LOGIN_URL}
+    validate-url: ${SSO_VALIDATE_URL}

package/templates/valid-group/ValidGroup.hbs

@@ -0,0 +1,20 @@
+package {{basePackage}}.validation;
+
+/**
+ * Bean Validation 的 groups。Controller 用 {@code @Validated(ValidGroup.Create.class)}，
+ * 欄位的 {@code groups} 對同一組，這樣 create 與 update 可以套不同必填規則。
+ */
+public interface ValidGroup {
+
+    /** 新增時要檢查的欄位。 */
+    interface Create {}
+
+    /** 更新時要檢查的欄位。 */
+    interface Update {}
+
+    /** 刪除還要帶 body 時用：原因、確認碼、樂觀鎖 version。只刪 id 就不用這組。 */
+    interface Delete {}
+
+    /** 送審／提交：比草稿更嚴。草稿走 Create，送審改 @Validated(Submit.class)。 */
+    interface Submit {}
+}

package/test.md

@@ -0,0 +1,56 @@
+# test
+
+實作時測試怎麼寫。流程在 [implement.md](implement.md)；規範在 [PROJECT.md](PROJECT.md)。這份只管圍欄。
+
+目標不是「讓測試變綠」，是「有問題的碼過不了關」。
+
+## 工具
+
+沿用 `node --test`（`npm test`）。Given-When-Then 寫在**測試名稱**，例如 `add 第二次不改檔、.bircrc.json.features 只有一個同名 key`。不要另開 `.feature` runner。
+
+覆蓋率與變異測試是這份 repo 的硬門檻，不是某一張票順便加的：
+
+- `npm run test:coverage`：`c8` 打 `plopfile.js`、`versions.js`、`bin/cli-util.js`，行／函式／陳述 < 80% 或分支 < 65% 就失敗。安裝／更新的 tar 跳脫與自訂 URL 另有定向測試，不拿整份 `home-install.js` 湊門檻。
+- `npm run test:mutation`：Stryker 打 `bin/cli-util.js`（路徑、Gradle wrapper、create 預設），突變分數 < 70 就失敗。`plopfile.js` 的全量突變會重跑 `./gradlew test`，太慢，關鍵路徑改完仍做一次**人工突變**。
+
+`.gitlab-ci.yml` 跑這兩道；紅了不能合。過程中跑單一測試；完整 `npm test` 只在 implement 最後一次（裡面會 `create` / `add` / `./gradlew test`）。
+
+## 打在哪
+
+測試打在使用者拿得到的結果：`create` / `add` / `injectDocs` 之後專案裡的檔、CLI 旗標生出的 dest、產出 Java 的 import。注入文件鎖 dest 的 `AGENTS.md` / `PROJECT.md`，不要讀 generator 裡的 `.hbs`。
+
+不斷言 template 排版或 private helper 名稱。預期值來自規格或已知字面，不要用實作自己算一遍再跟自己比。
+
+每條關鍵測試要寫得出「這條防住什麼」。
+
+## 關鍵路徑 vs 低風險
+
+火力只打關鍵路徑。出錯會讓使用者專案壞掉或資料錯的，算關鍵：
+
+- `create` / `add` 對同一 feature 生出同一組檔與同一段 yml/gradle；重複 `add` 零變更；anchor 還在。
+- `add` 冪等：已記在 `.bircrc.json.features` 的不再執行；舊專案漏記時既有檔與 fragment 也要跳過。
+- `add` 預檢查：要插 yml / gradle 時 dest 沒有 anchor 就失敗，且不能留下新的 Java 檔。缺 plugin-anchor 時不寫 `spotless_formatter.xml`。
+- 全 feature `create` + `make User` 之後 `./gradlew test` 與 `./gradlew spotlessCheck` 都過。
+- `add --force` / `sync`：覆寫已安裝 feature 的檔，yml / gradle 不重貼。
+- CLI dest：檔落在呼叫者目錄，不是 generator repo。
+- 產出 Java 沒有 `tw.edu.ntub.birc.starter` / `birc-spring-boot-starter`。
+- `make:entity --dto` / `--mapper` 與 `make:mapper` 同一組 Mapper + DTO；預設 `make:entity` 不生它們。
+- `make:model --migration` / `--seed` 的表名跟 Entity `@Table` 一致；migration 與 seed 版本號不重複。
+- `--soft-delete` 的 Entity 用 `deleted_at` + `SoftDeleteType.TIMESTAMP`；沒加 flag 的 Entity / migration 沒有這欄。
+- `--example` 的驗證群組是專案 `ValidGroup.Create` / `Update`，不是 starter `OnCreate`。`Delete` / `Submit` 是空的 marker，給「刪除要帶 body」與送審用，預設 CRUD 不標；不要刪掉。
+- Flyway plugin 版本跟得上 Gradle wrapper；`flywayMigrate` 不能再碰到已刪的 Gradle convention API。
+- 安裝／更新路徑：`detectInstallKind`、自訂 base URL 預設拒絕、tarball 路徑不可逃出目標目錄。
+
+低風險：help 用字、banner 日期、純文件潤飾、label 中英對照。最多一條鎖定文案，或零測試。
+
+## 原則
+
+1. 合法會過，非法被拒（重複 add、壞名稱、不該存在的 starter import）。
+2. 不變量優先：anchor 行還在、features 沒有重複 key、第二次 add 的 snapshot 不變。
+3. 時間敏感邏輯注入可控時間，不用 `sleep`。
+4. 這個 generator 沒有金額／庫存競態，不要為了清單去造假共享狀態。產出 Spring 專案的報名／扣庫存，測在產出專案。
+5. 至少一次**人工突變**：改壞剛寫的關鍵斷言或實作，確認對應測試轉紅，再改回來。這補 Stryker 打不到的 `plopfile.js` / template 路徑。
+
+覆蓋率、Stryker、pipeline 都已是硬門檻：`npm test` 綠不夠，還要 `npm run test:coverage` 與 `npm run test:mutation` 過。
+
+完成條件：關鍵路徑有正反案例；低風險沒被拿去湊數量；做過一次人工突變。

package/uninstall.ps1

@@ -0,0 +1,60 @@
+# 用法:
+#   irm https://gitlab.ntubimdbirc.tw/lucashsu95/birc-generator/-/raw/main/uninstall.ps1 | iex
+# 或下載後執行: powershell -NoProfile -ExecutionPolicy Bypass -File uninstall.ps1
+# 只拆 curl / PowerShell 裝到 $HOME\.birc-generator 的那份，不會 npm uninstall -g。
+
+$ErrorActionPreference = 'Stop'
+
+function Write-Info([string]$Message) {
+    Write-Host "[INFO] $Message" -ForegroundColor Green
+}
+
+function Write-Warn([string]$Message) {
+    Write-Host "[WARN] $Message" -ForegroundColor Yellow
+}
+
+function Remove-Cmd([string]$Target) {
+    if (-not (Test-Path $Target)) {
+        return
+    }
+    try {
+        Remove-Item -Force $Target
+        Write-Info "已移除 $Target"
+    } catch {
+        Write-Warn "無法移除 $Target"
+    }
+}
+
+function Remove-Shims {
+    $candidates = New-Object System.Collections.Generic.List[string]
+    $candidates.Add((Join-Path $HOME '.local\bin')) | Out-Null
+    try {
+        $prefix = (& npm config get prefix 2>$null).Trim()
+        if ($prefix) {
+            $candidates.Add($prefix) | Out-Null
+            $candidates.Add((Join-Path $prefix 'bin')) | Out-Null
+        }
+    } catch {
+        # npm 不在就算了
+    }
+
+    foreach ($dir in $candidates) {
+        Remove-Cmd (Join-Path $dir 'birc')
+        Remove-Cmd (Join-Path $dir 'birc.cmd')
+        Remove-Cmd (Join-Path $dir 'birc.ps1')
+    }
+}
+
+Write-Info '開始解除安裝 birc-generator...'
+Remove-Shims
+
+$installDir = Join-Path $HOME '.birc-generator'
+if (Test-Path $installDir) {
+    Write-Info "移除安裝目錄: $installDir"
+    Remove-Item -Recurse -Force $installDir
+} else {
+    Write-Info "安裝目錄不存在: $installDir"
+}
+
+Write-Info '解除安裝完成。birc 指令與 ~/.birc-generator 已移除。'
+Write-Info '若當初是 npm i -g 裝的，請改跑 npm uninstall -g birc-generator。'

package/uninstall.sh

@@ -0,0 +1,76 @@
+#!/bin/bash
+set -e
+
+# birc-generator 解除安裝腳本
+# 用法: bash uninstall.sh
+
+# 顏色定義
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+NC='\033[0m' # No Color
+
+# 輸出函數
+info() { echo -e "${GREEN}[INFO]${NC} $1"; }
+warn() { echo -e "${YELLOW}[WARN]${NC} $1"; }
+error() { echo -e "${RED}[ERROR]${NC} $1"; exit 1; }
+
+remove_cmd() {
+    local target="$1"
+    if [ -e "$target" ] || [ -L "$target" ]; then
+        if [ -w "$(dirname "$target")" ]; then
+            rm -f "$target"
+            info "已移除 $target"
+        else
+            warn "無法移除 $target（沒有寫入權限）"
+        fi
+    fi
+}
+
+remove_symlink() {
+    local npm_prefix=""
+    remove_cmd /usr/local/bin/birc
+    remove_cmd "$HOME/.local/bin/birc"
+    npm_prefix="$(npm config get prefix 2>/dev/null || true)"
+    if [ -n "$npm_prefix" ]; then
+        remove_cmd "$npm_prefix/bin/birc"
+        remove_cmd "$npm_prefix/bin/birc.cmd"
+        remove_cmd "$npm_prefix/birc"
+        remove_cmd "$npm_prefix/birc.cmd"
+    fi
+}
+
+# 移除安裝目錄
+remove_install_dir() {
+    local INSTALL_DIR="$HOME/.birc-generator"
+    
+    if [ -d "$INSTALL_DIR" ]; then
+        info "移除安裝目錄: $INSTALL_DIR"
+        rm -rf "$INSTALL_DIR"
+    else
+        info "安裝目錄不存在: $INSTALL_DIR"
+    fi
+}
+
+# 清除 npm 全域快取（如果有）
+clear_npm_cache() {
+    if command -v npm &> /dev/null; then
+        info "清除 npm 快取..."
+        npm cache clean --force 2>/dev/null || true
+    fi
+}
+
+# 主函數
+main() {
+    info "開始解除安裝 birc-generator..."
+    
+    remove_symlink
+    remove_install_dir
+    clear_npm_cache
+    
+    info "解除安裝完成！"
+    info "birc 指令已移除，安裝目錄已刪除。"
+}
+
+# 執行主函數
+main "$@"

package/versions.js

@@ -0,0 +1,10 @@
+module.exports = Object.freeze({
+  springBootVersion: '4.0.5',
+  dependencyManagementVersion: '1.1.7',
+  flywayVersion: '11.14.1',
+  sentryVersion: '8.40.0',
+  springdocVersion: '3.0.2',
+  mapstructVersion: '1.6.3',
+  lombokMapstructBindingVersion: '0.2.0',
+  spotlessVersion: '6.25.0'
+});