refactor(tools): modularize CLI with urfave/cli/v2, externalise template metadata

- Split monolithic build-preview.go into modular packages: tools.go (entry), cli/ (list/create/delete/preview commands), config/ (JSON loading), preview/ (rendering engine, funcs, locale) - Extract all template metadata into data/templates_config.json as single source of truth — no hardcoded template data in Go - Replace hand-rolled CLI parsing with github.com/urfave/cli/v2 - Add sensible defaults for --folder (../themes) and --config (./data/templates_config.json) — most commands now run bare - Add type-coercing gt/lt/ge/le template funcs for JSON float64 - Fix AppUrl to gitea.com matching official template convention - rendered.js now exports __REGISTRY__ and __PARAMS__ alongside __RENDERED__ — preview/index.html reads all from single source - Cross-validate all 11 template data contexts against official Gitea source (services/mailer/*.go + templates/mail/*.tmpl) - Update all docs (README, AGENTS, CONTRIBUTING, 5 languages) to reflect new CLI workflow with create scaffolding command Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-06-04 12:26:44 +08:00
1 parent 77854ee0ed
commit 0bf982ffb9
@@ -4,12 +4,10 @@

 ### 新しいスタイルの追加

-1. スタイルディレクトリを作成: `themes/<style-name>/`
-2. 既存スタイルからディレクトリ構造をコピー
-3. 11個の `.tmpl` ファイルを独自デザインで実装
-4. プレビューを再生成: `go run ./tools/build-preview.go`（ビルドスクリプトが `themes/` 以下の全テーマを自動検出します）
-5. `preview/index.html` の `<select id="sel-theme">` に追加
-6. スクリーンショット付きで PR を提出
+1. ツールでスキャフォールド: `cd tools && go run . create <style-name>` — 全11種類のメールタイプ用のプレースホルダ `.tmpl` ファイルを含む完全なディレクトリ構造を作成します
+2. `themes/<style-name>/` 内の各 `.tmpl` ファイルを独自デザインで編集
+3. プレビューを再生成: `cd tools && go run . preview all`（ビルドスクリプトが `themes/` 以下の全テーマを自動検出し、テーマセレクターも自動生成されます）
+4. スクリーンショット付きで PR を提出

 ### スタイルガイドライン

@@ -25,7 +23,7 @@
 1. Go 変数が正しいか確認
 2. 翻訳キーが Gitea ロケールと一致するか確認
 3. `.DisplayName` が誤用されていないか確認
-4. プレビューを再生成: `go run ./tools/build-preview.go`
+4. プレビューを再生成: `cd tools && go run . preview all`
 5. スタイル名とメールタイプを明記して issue を作成

 ---
@@ -34,7 +32,7 @@

 ### ローカルプレビュー

-1. データを生成: `go run ./tools/build-preview.go`
+1. データを生成: `cd tools && go run . preview all`
 2. `preview/index.html` をブラウザで開く
 3. Modern, Gmail, Outlook, Raw source を切り替えて確認

@@ -4,12 +4,10 @@

 ### 새 스타일 추가하기

-1. 스타일 디렉토리 생성: `themes/<style-name>/`
-2. 기존 스타일에서 디렉토리 구조 복사
-3. 11개 `.tmpl` 파일을 고유한 디자인으로 구현
-4. 프리뷰 재생성: `go run ./tools/build-preview.go` (빌드 스크립트가 `themes/` 아래의 모든 테마 디렉토리를 자동으로 찾습니다)
-5. `preview/index.html`의 `<select id="sel-theme">`에 추가
-6. 스크린샷과 함께 PR 제출
+1. 도구로 스캐폴드: `cd tools && go run . create <style-name>` — 11개 이메일 유형 모두에 대한 플레이스홀더 `.tmpl` 파일이 포함된 완전한 디렉토리 구조를 생성합니다
+2. `themes/<style-name>/`에서 각 `.tmpl` 파일을 고유한 디자인으로 편집
+3. 프리뷰 재생성: `cd tools && go run . preview all` (빌드 스크립트가 `themes/` 아래의 모든 테마 디렉토리를 자동으로 찾고 테마 선택기도 자동 생성합니다)
+4. 스크린샷과 함께 PR 제출

 ### 스타일 가이드라인

@@ -25,7 +23,7 @@
 1. Go 변수가 올바른지 확인
 2. 번역 키가 Gitea 로케일과 일치하는지 확인
 3. `.DisplayName`이 오용되지 않았는지 확인
-4. 프리뷰 재생성: `go run ./tools/build-preview.go`
+4. 프리뷰 재생성: `cd tools && go run . preview all`
 5. 스타일 이름과 메일 유형을 명시하여 이슈 생성

 ---
@@ -34,7 +32,7 @@

 ### 로컬 프리뷰

-1. 데이터 생성: `go run ./tools/build-preview.go`
+1. 데이터 생성: `cd tools && go run . preview all`
 2. `preview/index.html`을 브라우저에서 열기
 3. Modern, Gmail, Outlook, Raw source 모드 전환 확인

@@ -4,12 +4,10 @@

 ### Добавление нового стиля

-1. Создайте директорию стиля: `themes/<имя-стиля>/`
-2. Скопируйте структуру из существующего стиля
-3. Реализуйте все 11 `.tmpl` файлов с уникальным дизайном
-4. Перегенерируйте превью: `go run ./tools/build-preview.go` (скрипт автоматически находит все темы в `themes/`)
-5. Добавьте тему в `<select id="sel-theme">` в `preview/index.html`
-6. Отправьте PR со скриншотами
+1. Создайте каркас через инструмент: `cd tools && go run . create <имя-стиля>` — создаёт полную структуру директорий с файлами-заготовками `.tmpl` для всех 11 типов писем
+2. Отредактируйте каждый `.tmpl` файл в `themes/<имя-стиля>/` с вашим уникальным дизайном
+3. Перегенерируйте превью: `cd tools && go run . preview all` (скрипт автоматически находит все темы в `themes/` и динамически генерирует селектор тем)
+4. Отправьте PR со скриншотами

 ### Рекомендации по стилю

@@ -25,7 +23,7 @@
 1. Проверьте переменные Go в шаблонах
 2. Сверьте ключи перевода с локалью Gitea
 3. Убедитесь что `.DisplayName` не используется где не надо
-4. Перегенерируйте превью: `go run ./tools/build-preview.go`
+4. Перегенерируйте превью: `cd tools && go run . preview all`
 5. Создайте issue с указанием стиля и типа письма

 ---
@@ -34,7 +32,7 @@

 ### Локальный предпросмотр

-1. Сгенерируйте данные: `go run ./tools/build-preview.go`
+1. Сгенерируйте данные: `cd tools && go run . preview all`
 2. Откройте `preview/index.html` в браузере
 3. Переключайте Modern, Gmail, Outlook, Raw source для проверки

@@ -4,12 +4,10 @@

 ### 添加新风格

-1. 创建风格目录：`themes/<风格名称>/`
-2. 从现有风格复制目录结构
-3. 用独特的视觉设计实现全部 11 个 `.tmpl` 文件
-4. 重新生成预览：`go run ./tools/build-preview.go`（构建脚本会自动发现 `themes/` 下的所有主题目录）
-5. 在 `preview/index.html` 的 `<select id="sel-theme">` 中添加选项
-6. 提交包含截图渲染效果的 PR
+1. 使用工具脚手架：`cd tools && go run . create <风格名称>` — 这会创建完整的目录结构和全部 11 种邮件类型的占位 `.tmpl` 文件
+2. 在 `themes/<风格名称>/` 中编写每个 `.tmpl` 文件，应用独特的视觉设计
+3. 重新生成预览：`cd tools && go run . preview all`（构建脚本会自动发现 `themes/` 下的所有主题目录并动态生成主题选择器）
+4. 提交包含截图渲染效果的 PR

 ### 风格指南

@@ -25,7 +23,7 @@
 1. 检查引用的 Go 模板变量是否存在
 2. 验证翻译键是否与 Gitea 语言文件匹配
 3. 确认 `.DisplayName` 未在不支持的模板中使用
-4. 重新生成预览：`go run ./tools/build-preview.go`
+4. 重新生成预览：`cd tools && go run . preview all`
 5. 提交 issue，注明风格名称、邮件类型及错误描述

 ### 改进文档
@@ -40,7 +38,7 @@

 ### 本地预览

-1. 先生成预览数据：`go run ./tools/build-preview.go`
+1. 先生成预览数据：`cd tools && go run . preview all`
 2. 在浏览器中打开 `preview/index.html`
 3. 在 Modern、Gmail、Outlook、Raw source 模式间切换验证效果

@@ -4,12 +4,10 @@

 ### 新增風格

-1. 建立風格目錄：`themes/<風格名稱>/`
-2. 從現有風格複製目錄結構
-3. 以獨特的視覺設計實作全部 11 個 `.tmpl` 檔案
-4. 重新產生預覽：`go run ./tools/build-preview.go`（建置腳本會自動發現 `themes/` 下的所有主題目錄）
-5. 在 `preview/index.html` 的 `<select id="sel-theme">` 中新增選項
-6. 提交包含螢幕截圖的 PR
+1. 使用工具腳手架：`cd tools && go run . create <風格名稱>` — 這會建立完整的目錄結構和全部 11 種郵件類型的佔位 `.tmpl` 檔案
+2. 在 `themes/<風格名稱>/` 中編寫每個 `.tmpl` 檔案，套用獨特的視覺設計
+3. 重新產生預覽：`cd tools && go run . preview all`（建置腳本會自動發現 `themes/` 下的所有主題目錄並動態生成主題選擇器）
+4. 提交包含螢幕截圖的 PR

 ### 風格指南

@@ -25,7 +23,7 @@
 1. 檢查引用的 Go 模板變數是否存在
 2. 驗證翻譯鍵是否與 Gitea 語系檔案相符
 3. 確認 `.DisplayName` 未在不支援的模板中使用
-4. 重新產生預覽：`go run ./tools/build-preview.go`
+4. 重新產生預覽：`cd tools && go run . preview all`
 5. 提交 issue，註明風格名稱、郵件類型及錯誤描述

 ### 改善文件
@@ -40,7 +38,7 @@

 ### 本機預覽

-1. 先生成預覽資料：`go run ./tools/build-preview.go`
+1. 先生成預覽資料：`cd tools && go run . preview all`
 2. 在瀏覽器中開啟 `preview/index.html`
 3. 在 Modern、Gmail、Outlook、Raw source 模式間切換驗證效果

@@ -37,7 +37,7 @@ systemctl restart gitea
 ## プレビュー

 ```bash
-go run ./tools/build-preview.go
+cd tools && go run . preview all
 ```
 その後 `preview/index.html` を開く。

@@ -37,7 +37,7 @@ systemctl restart gitea
 ## 프리뷰

 ```bash
-go run ./tools/build-preview.go
+cd tools && go run . preview all
 ```
 그런 다음 `preview/index.html` 열기.

@@ -37,7 +37,7 @@ systemctl restart gitea
 ## Предпросмотр

 ```bash
-go run ./tools/build-preview.go
+cd tools && go run . preview all
 ```
 Затем откройте `preview/index.html`.

@@ -51,7 +51,7 @@ systemctl restart gitea
 ## 预览

 ```bash
-go run ./tools/build-preview.go
+cd tools && go run . preview all
 ```
 然后打开 `preview/index.html`。

@@ -51,7 +51,7 @@ systemctl restart gitea
 ## 預覽

 ```bash
-go run ./tools/build-preview.go
+cd tools && go run . preview all
 ```
 然後開啟 `preview/index.html`。

@@ -11,7 +11,7 @@ neon.png       mono.png        terra.png    ink.png      aurora.png

 ## How to Capture

-1. Run `go run ./tools/build-preview.go` from the project root
+1. Run `cd tools && go run . preview all` from the project root
 2. Open `preview/index.html` in a browser
 3. For each style, select the "Activate Account" template and "Modern" client mode
 4. Take a screenshot of the rendered email (600px width recommended)