create-halo-plugin-template 1.0.0 → 1.0.1

package/README.md

@@ -0,0 +1,191 @@
+# Halo Plugin Template
+
+通用的 Halo 插件开发模板，基于官方 `pnpm create halo-plugin` 的 Vite 预设收敛而成。
+
+这个模板默认提供：
+
+- Java 21 + Halo Plugin DevTools 基线
+- `@halo-dev/ui-shared` + `@halo-dev/components` + Element Plus 的 UI 组合
+- Console / UC 路由骨架
+- 仪表盘小部件、快速操作项、附件选择器扩展点示例
+- `settings.yaml`、Console/UC 角色模板、OpenAPI 客户端生成配置
+- 已接线的 `ui/src/api/generated` + `ui/src/api/index.ts` API 包装层
+- 一次性初始化脚本，用于批量改插件名、包名、权限前缀和仓库信息
+
+## 环境要求
+
+- Java 21+
+- Node.js 22+
+- pnpm 10+
+- Docker（推荐，用于 `haloServer`）
+
+## 快速开始
+
+推荐直接用一键脚本从当前模板创建新项目目录：
+
+```bash
+node scripts/create-project.mjs \
+  --plugin-name hello-world \
+  --base-package com.example.helloworld \
+  --display-name "Hello World" \
+  --author-name "Your Name" \
+  --target-dir ../hello-world \
+  --install \
+  --build
+```
+
+这个脚本会自动完成：
+
+- 复制模板到目标目录
+- 执行 `init-template.mjs`
+- 执行 `verify-template.mjs`
+- 可选安装前端依赖
+- 可选执行 `./gradlew build`
+
+如果你已经手工复制好了目录，再使用下面的初始化方式也可以。
+
+如果你后续把这个模板发布成 npm 的 `create-*` 包，还可以直接远程一键创建：
+
+```bash
+npm create halo-plugin-template@latest -- \
+  --plugin-name hello-world \
+  --base-package com.example.helloworld \
+  --display-name "Hello World" \
+  --author-name "Your Name"
+```
+
+发布说明见 [docs/publish-template.md](./docs/publish-template.md)。
+首发操作清单见 [docs/first-npm-release-checklist.md](./docs/first-npm-release-checklist.md)。
+
+当前 GitHub 仓库名和 unscoped npm 包名统一为 `create-halo-plugin-template`，便于后续维护和分发。
+
+如果你要在发布前做一次完整自检，直接执行：
+
+```bash
+npm run publish:check
+```
+
+如果你要准备一个新版本发布，可以直接执行：
+
+```bash
+npm run release:prepare -- --bump patch
+```
+
+如果你已经在 npm 侧配置好了 Trusted Publishing，并且希望本地完成检查、提交、打 tag、推送一条龙：
+
+```bash
+npm run release:prepare -- --bump patch --push
+```
+
+这条命令会自动：
+
+- 校验当前分支必须是 `main`
+- 校验工作区必须是干净状态
+- 更新根目录 `package.json` 的版本号
+- 执行 `npm run publish:check`
+- 创建 `chore: release vX.Y.Z` 提交
+- 创建 `vX.Y.Z` tag
+- 可选推送 `main` 和 tag
+
+仓库当前使用 `push tag -> publish-npm.yaml` 的方式触发 npm 发布。
+
+先运行初始化脚本，把模板占位符替换成你的插件信息：
+
+```bash
+node scripts/init-template.mjs \
+  --plugin-name hello-world \
+  --base-package com.example.helloworld \
+  --display-name "Hello World" \
+  --author-name "Your Name" \
+  --author-website "https://github.com/your-name" \
+  --repo-owner your-name \
+  --description "Hello World - Halo 插件"
+```
+
+这个脚本是一次性的。执行后会连同自身模板常量一起改写，确保生成出来的项目里不再残留模板占位符。
+
+初始化完成后，马上执行一次模板一致性检查：
+
+```bash
+node scripts/verify-template.mjs \
+  --plugin-name hello-world \
+  --base-package com.example.helloworld \
+  --display-name "Hello World" \
+  --author-name "Your Name"
+```
+
+然后安装前端依赖并启动开发环境：
+
+```bash
+pnpm install --dir ui
+./gradlew haloServer
+```
+
+如果只调试前端构建：
+
+```bash
+cd ui
+pnpm dev
+```
+
+## 常用命令
+
+```bash
+# 构建插件
+./gradlew build
+
+# 后端单测
+./gradlew test
+
+# 一致性检查
+node scripts/verify-template.mjs
+
+# 前端检查
+cd ui
+pnpm verify
+
+# 生成 OpenAPI 文档和 TS 客户端
+cd ..
+./gradlew generateApiClient
+
+# 基于 OpenAPI 生成角色模板草稿
+./gradlew generateRoleTemplates
+```
+
+## 目录说明
+
+- `src/main/java/`：后端骨架，按 `config / endpoint / query / service / scheme / reconcile / setting / utils` 分层
+- `src/main/resources/extensions/`：插件设置和角色模板
+- `ui/src/index.ts`：插件 UI 唯一注册入口
+- `ui/src/components/ui/`：低层通用 UI 包装
+- `ui/src/components/`：业务级共享组件
+- `ui/src/api/index.ts`：前端唯一 API 包装出口
+- `ui/src/api/generated/`：由 `generateApiClient` 生成并已接入的客户端代码
+- `docs/rsbuild-switch.md`：从当前模板切换到 Rsbuild 的最小差异说明
+- `docs/template-pruning.md`：初始化后如何裁剪模板能力的操作建议
+
+## OpenAPI 与角色模板
+
+模板已经预置了 `haloPlugin.openApi` 配置，默认会：
+
+- 输出 OpenAPI 文档到 `api-docs/openapi/v3_0`
+- 把生成的前端客户端输出到 `ui/src/api/generated`
+- 为 `generateRoleTemplates` 提供基础输入
+
+视图层不要直接写裸请求 URL，也不要直接 import 生成客户端，统一从 `ui/src/api/index.ts` 包装后再消费。
+
+## 初始化后裁剪
+
+主模板故意把 Console、UC、仪表盘、快捷操作、附件扩展和 PublicEndpoint 占位都带上了，方便你按需删减。
+
+- 若只做 Console 插件，可删除 UC 路由、UC 角色模板和相关设置。
+- 若不需要附件扩展或工作台小部件，可删除对应扩展点和配套组件。
+- 具体裁剪顺序见 [docs/template-pruning.md](./docs/template-pruning.md)。
+
+## Rsbuild
+
+主模板只维护 Vite 版本。若需要切换到 Rsbuild，请参考 [docs/rsbuild-switch.md](./docs/rsbuild-switch.md)。
+
+## 许可证
+
+[GPL-3.0](./LICENSE)

package/build.gradle

@@ -0,0 +1,103 @@
+plugins {
+    id 'java'
+    id "io.freefair.lombok" version "9.2.0"
+    id "run.halo.plugin.devtools" version "0.6.2"
+}
+
+group 'run.halo.plugintemplate'
+
+ext {
+    haloPlatformVersion = '2.23.0'
+    javaReleaseVersion = 21
+}
+
+repositories {
+    mavenCentral()
+}
+
+dependencies {
+    implementation platform("run.halo.tools.platform:plugin:$haloPlatformVersion")
+    compileOnly 'run.halo.app:api'
+
+    testImplementation 'run.halo.app:api'
+    testImplementation 'org.springframework.boot:spring-boot-starter-test'
+    testRuntimeOnly 'org.junit.platform:junit-platform-launcher'
+}
+
+test {
+    useJUnitPlatform()
+}
+
+java {
+    toolchain {
+        languageVersion = JavaLanguageVersion.of(javaReleaseVersion)
+    }
+}
+
+tasks.withType(JavaCompile).configureEach {
+    options.encoding = "UTF-8"
+    options.release = javaReleaseVersion
+}
+
+tasks.register('processUiResources', Copy) {
+    from project(':ui').layout.buildDirectory.dir('dist')
+    into layout.buildDirectory.dir('resources/main/console')
+    dependsOn project(':ui').tasks.named('assemble')
+    shouldRunAfter tasks.named('processResources')
+}
+
+tasks.named('classes') {
+    dependsOn tasks.named('processUiResources')
+}
+
+tasks.matching { it.name == 'haloServer' || it.name == 'createHaloContainer' }.configureEach {
+    dependsOn tasks.named('processUiResources')
+}
+
+tasks.named('generatePluginComponentsIdx') {
+    notCompatibleWithConfigurationCache('This task invokes "Task.project" at execution time, which is not supported with configuration cache.')
+}
+
+tasks.register('verifyTemplateConsistency', Exec) {
+    group = 'verification'
+    description = 'Verify the starter repository or initialized plugin stays internally consistent'
+    commandLine 'node', 'scripts/verify-template.mjs'
+}
+
+tasks.named('check') {
+    dependsOn tasks.named('verifyTemplateConsistency')
+}
+
+halo {
+    version = '2.23'
+}
+
+haloPlugin {
+    openApi {
+        outputDir = file("$rootDir/api-docs/openapi/v3_0")
+        groupingRules {
+            templateApis {
+                displayName = 'Extension API for halo-plugin-template'
+                pathsToMatch = [
+                        '/apis/console.halo-plugin-template.halo.run/v1alpha1/**',
+                        '/apis/uc.halo-plugin-template.halo.run/v1alpha1/**'
+                ]
+            }
+        }
+        groupedApiMappings = [
+                '/v3/api-docs/templateApis': 'templateApis.json'
+        ]
+        generator {
+            outputDir = file("${projectDir}/ui/src/api/generated")
+        }
+    }
+
+    watchDomains {
+        uiSource {
+            files files('ui/src/', 'ui/vite.config.ts', 'ui/package.json')
+        }
+        pluginSource {
+            files files('src/main/java/', 'src/main/resources/')
+        }
+    }
+}

package/docs/first-npm-release-checklist.md

@@ -0,0 +1,58 @@
+# First npm Release Checklist
+
+适用于仓库：`liuyiwuqing/create-halo-plugin-template`
+
+## 5 步完成首发
+
+1. 登录 npm 并确认账号有发布权限：
+
+```bash
+npm login
+npm whoami
+```
+
+2. 在 npm 后台创建包 `create-halo-plugin-template` 的 Trusted Publisher，绑定：
+
+- GitHub repository: `liuyiwuqing/create-halo-plugin-template`
+- Workflow file: `.github/workflows/publish-npm.yaml`
+- Environment: `npm`
+
+3. 在本地主分支确认工作区干净：
+
+```bash
+git checkout main
+git pull --ff-only
+git status --short
+```
+
+4. 准备并推送首个发布版本：
+
+```bash
+npm run release:prepare -- --version 0.1.0 --push
+```
+
+如果首发版本号已经改过，按实际版本替换 `0.1.0`。
+
+5. 到 GitHub Actions 查看 `Publish npm CLI` 工作流是否成功，并到 npm 验证包是否已发布：
+
+```bash
+npm view create-halo-plugin-template version
+```
+
+## 失败时先检查什么
+
+- npm Trusted Publisher 是否绑到了正确仓库和工作流文件
+- GitHub Actions environment 是否叫 `npm`
+- 本地是否在 `main` 分支
+- 工作区是否有未提交改动
+- 本地 tag 是否已经存在
+
+## 首发后创建项目
+
+```bash
+npm create halo-plugin-template@latest -- \
+  --plugin-name hello-world \
+  --base-package com.example.helloworld \
+  --display-name "Hello World" \
+  --author-name "Your Name"
+```

package/docs/publish-template.md

@@ -0,0 +1,148 @@
+# Publish The Template CLI
+
+这个模板仓库现在可以同时承担两种角色：
+
+1. Halo 插件模板源码仓库
+2. npm 上的 `create-*` 脚手架包
+
+如果你现在就是要做首发，直接看 [first-npm-release-checklist.md](./first-npm-release-checklist.md)。
+
+## 推荐发布方式
+
+### 方案一：npm `create-*` 包
+
+适合对外分发和一键创建：
+
+```bash
+npm create halo-plugin-template@latest -- \
+  --plugin-name hello-world \
+  --base-package com.example.helloworld \
+  --display-name "Hello World" \
+  --author-name "Your Name"
+```
+
+注意：
+
+- 当前模板已经把 GitHub 仓库名和 npm 包名统一为 `create-halo-plugin-template`。
+- 如果后续你还想再区分“源码仓库名”和“npm 包名”，优先考虑 scoped 包，而不是再拆回两套不一致命名。
+- 如果你坚持让包名进一步品牌化，建议改成 scoped 包，例如 `@liuyiwuqing/create-halo-plugin-template`。
+
+如果你改成 scoped 包名，例如 `@your-scope/create-halo-plugin-template`，对应命令建议写成：
+
+```bash
+npm init @your-scope/halo-plugin-template@latest -- \
+  --plugin-name hello-world \
+  --base-package com.example.helloworld \
+  --display-name "Hello World" \
+  --author-name "Your Name"
+```
+
+### 方案二：GitHub Template Repository
+
+适合团队内部维护“源码基线”，但不适合交互式参数初始化。通常建议保留，用来承载源码和 PR 审核；npm 包只负责分发最新模板。
+
+## 第一次发布前
+
+1. 检查根目录 `package.json` 的 `name`、`version`、`description`、`homepage`、`repository`、`bugs` 是否仍然指向当前仓库。
+   当前模板已经按 `liuyiwuqing/create-halo-plugin-template` 预填。
+2. 执行：
+
+```bash
+npm run publish:check
+```
+
+3. 确认打包内容只包含模板和 CLI 所需文件。
+4. 登录 npm：
+
+```bash
+npm login
+```
+
+5. 在 npm 后台为包 `create-halo-plugin-template` 配置 Trusted Publisher，绑定：
+
+- GitHub repository: `liuyiwuqing/create-halo-plugin-template`
+- Workflow file: `.github/workflows/publish-npm.yaml`
+- Environment: `npm`
+
+## 发布命令
+
+### 一键准备下个版本
+
+```bash
+npm run release:prepare -- --bump patch
+```
+
+这会自动完成版本号更新、发布前检查、提交和打 tag。
+
+### 一键准备并推送发布
+
+```bash
+npm run release:prepare -- --bump patch --push
+```
+
+这会在本地完成检查后直接推送 `main` 和 `vX.Y.Z` tag。
+当前仓库使用 tag push 触发 [publish-npm.yaml](../.github/workflows/publish-npm.yaml)，所以只要 npm Trusted Publishing 已经配置好，推送 tag 后就会自动发布。
+
+### 手工发布
+
+```bash
+npm publish
+```
+
+### scoped 公共包手工发布
+
+```bash
+npm publish --access public
+```
+
+### 指定版本号准备发布
+
+```bash
+npm run release:prepare -- --version 1.0.0
+```
+
+或者直接推送：
+
+```bash
+npm run release:prepare -- --version 1.0.0 --push
+```
+
+## 持续发布建议
+
+- GitHub 仓库继续作为模板源码主仓库。
+- npm 包只跟模板版本，不跟具体业务插件版本混用。
+- 每次模板有破坏性修改时，提升主版本号。
+- 发布前至少执行：
+
+```bash
+node scripts/verify-template.mjs
+cd ui && pnpm verify
+cd .. && ./gradlew build
+npm pack --dry-run
+```
+
+## CI 发布
+
+如果你要做自动发布，优先用 npm Trusted Publishing，而不是长期有效的 npm token。
+
+- 源码仓库推送 `v*` tag
+- GitHub Actions 触发 [publish-npm.yaml](../.github/workflows/publish-npm.yaml) 工作流
+- npm 侧配置 Trusted Publisher
+
+Trusted Publisher 里要填写的工作流文件名必须和仓库里的一致，也就是 `publish-npm.yaml`。
+
+另外，npm 官方目前要求 Trusted Publishing 使用 npm CLI `11.5.1+` 和 Node `22.14.0+`；工作流里已经显式升级到了这个版本线。
+
+## 平台建议
+
+- 对外开源分发：npm + GitHub Template Repository
+- 团队内私有分发：GitHub Template Repository + GitHub Release tarball
+- 需要固定版本初始化：npm 最方便，因为天然支持 `@latest` 或指定版本
+
+## 当前仓库绑定
+
+- GitHub owner: `liuyiwuqing`
+- GitHub repository: `create-halo-plugin-template`
+- npm package: `create-halo-plugin-template`
+- Homepage: `https://github.com/liuyiwuqing/create-halo-plugin-template#readme`
+- Issues: `https://github.com/liuyiwuqing/create-halo-plugin-template/issues`

package/docs/rsbuild-switch.md

@@ -0,0 +1,90 @@
+# 从 Vite 切换到 Rsbuild
+
+这个模板只维护一套 Vite 主线。如果你的插件前端体量变大，或者希望切到 Rspack 生态，可以按下面的最小差异切换到 Rsbuild。
+
+## 需要保留不动的部分
+
+这些文件不用改：
+
+- `build.gradle`
+- `settings.gradle`
+- `src/main/resources/plugin.yaml`
+- `src/main/resources/extensions/*`
+- `ui/src/index.ts`
+- `ui/src/api/*`
+
+模板里真正和 bundler 绑定的部分，只有 `ui/package.json` 与构建配置文件。
+
+## 变更步骤
+
+1. 替换 `ui/package.json` 的脚本与依赖
+
+把：
+
+```json
+"build-only": "vite build",
+"dev": "vite build --watch --mode=development"
+```
+
+替换成：
+
+```json
+"build-only": "rsbuild build",
+"dev": "rsbuild build --watch --env-mode=development"
+```
+
+把 `vite` 从 `devDependencies` 移除，新增：
+
+```json
+"@rsbuild/core": "^1.7.3",
+"@rsbuild/plugin-sass": "^1.5.0"
+```
+
+2. 新建 `ui/rsbuild.config.ts`
+
+```ts
+import { rsbuildConfig } from '@halo-dev/ui-plugin-bundler-kit'
+import type { RsbuildConfig } from '@rsbuild/core'
+import { pluginSass } from '@rsbuild/plugin-sass'
+import Icons from 'unplugin-icons/rspack'
+
+export default rsbuildConfig({
+  rsbuild: {
+    resolve: {
+      alias: {
+        '@': './src',
+      },
+    },
+    plugins: [pluginSass()],
+    tools: {
+      rspack: {
+        plugins: [Icons({ compiler: 'vue3' })],
+      },
+    },
+  },
+}) as RsbuildConfig
+```
+
+3. 删除 `ui/vite.config.ts`
+
+Rsbuild 启用后不再需要 Vite 配置文件。
+
+## 验证
+
+完成后执行：
+
+```bash
+pnpm install --dir ui
+cd ui
+pnpm build
+pnpm dev
+```
+
+然后回到项目根目录执行：
+
+```bash
+./gradlew build
+./gradlew haloServer
+```
+
+如果你只是为了试验构建性能，不要复制第二套 `ui-*` 目录；保持一套模板源代码，只切 bundler。

package/docs/template-pruning.md

@@ -0,0 +1,43 @@
+# Template Pruning Guide
+
+这个 starter 预置的是“可删减的上限”，不是要求每个插件都把所有模块保留下来。
+
+## 建议保留
+
+- `src/main/resources/plugin.yaml`、`settings.yaml`、角色模板：这是 Halo 插件最稳定的元数据骨架。
+- `ui/src/index.ts`：继续作为唯一 UI 注册出口，避免路由、扩展点和权限定义分散。
+- `ui/src/api/index.ts`：所有前端请求统一经过这一层，不要在页面里直连生成客户端或裸 URL。
+- `scripts/init-template.mjs` 和 `scripts/verify-template.mjs`：一个负责初始化，一个负责验收，后续孵化多个插件时都能复用。
+
+## 按需删除
+
+- 不需要 User Center 时：
+  删除 `PluginTemplateUcEndpoint`、`roleTemplate-uc.yaml`、`ucRoutes` 和相关 `enableUcDashboard` 设置。
+- 不需要附件扩展标签页时：
+  删除 `PluginTemplateAttachmentTab.vue`、`attachment:selector:create` 扩展点和 `enableAttachmentProvider` 设置。
+- 不需要工作台小部件或快速操作时：
+  删除 `PluginTemplateDashboardWidget.vue`、`console:dashboard:*` 扩展点，以及对应权限项。
+- 不需要公共 API 时：
+  保留 `PluginTemplatePublicEndpoint.java` 作为占位即可，真正需要公开接口时再加 `@Component` 和路由。
+
+## 增量开发顺序
+
+1. 先补后端接口和 Springdoc 注解。
+2. 执行 `./gradlew generateApiClient` 更新 `ui/src/api/generated/`。
+3. 只在 `ui/src/api/index.ts` 暴露业务可用的 API 包装。
+4. 页面和组件只依赖本地包装层，不直接引用生成客户端。
+
+## 初始化后的最小验收
+
+```bash
+node scripts/verify-template.mjs \
+  --plugin-name hello-world \
+  --base-package com.example.helloworld \
+  --display-name "Hello World" \
+  --author-name "Your Name"
+
+./gradlew build
+cd ui && pnpm test:unit
+```
+
+如果模板已经剪裁过，只要 `verify-template.mjs` 和构建通过，就说明插件的基础边界仍然一致。

package/gradle/wrapper/gradle-wrapper.properties

@@ -0,0 +1,7 @@
+distributionBase=GRADLE_USER_HOME
+distributionPath=wrapper/dists
+distributionUrl=https\://services.gradle.org/distributions/gradle-9.4.0-bin.zip
+networkTimeout=10000
+validateDistributionUrl=true
+zipStoreBase=GRADLE_USER_HOME
+zipStorePath=wrapper/dists

package/gradle.properties

@@ -0,0 +1 @@
+version=1.0.0-SNAPSHOT