ugp 1.0.0

ugp-1.0.0 is not a library.

ugp CLI 使用说明

顶层命令总览（`ugp -h`）

在仓库根目录执行：

// 本地安装并执行
cargo install --path . && ugp publish --stable --only-publish
cargo run -p ugp -- -h

典型输出如下（与实际版本号略有差异属于正常）：

ugp 0.9.8
仅适用用内部环境使用！应用快速发布工具，支持配置初始化（init）， 版本号更新（next）和一键发布（publish）流程

Usage: ugp [OPTIONS] <COMMAND>

Commands:
  publish  发布
  next     下一个版本
  init     初始化
  help     Print this message or the help of the given subcommand(s)

Options:
  -v, --verbose  启用详细日志模式
  -h, --help     Print help
  -V, --version  Print version

含义说明：

publish：发布相关流程（构建安装包 + 生成发布文件 + 版本历史维护）
next：计算下一个版本号（major/minor/patch/next/custom）
init：初始化 .ugp 目录及配置文件
help：查看整个 CLI 或某个子命令的使用说明（例如 ugp publish --help）
-v/--verbose：打开详细日志输出，方便排查发布问题

ugp 是配套的发布辅助 CLI，用于：

读取 src-tauri/tauri.conf.json 中的应用信息（名称、版本）
根据 .ugp/config.toml 的配置生成升级包发布文件
生成/维护 .ugp/version 下的版本信息（历史版本）

推荐在仓库根目录运行以下命令。

1. 初始化配置 `ugp init`

cargo run -p ugp -- init

引导创建 .ugp/config.toml
建议把 .ugp 目录加入版本控制，方便团队共享配置

2. 计算下一个版本号 `ugp next`

cargo run -p ugp -- next

行为：

从 src-tauri/tauri.conf.json 读取当前版本（例如 2.3.24）
提供以下选项：
- major：2.3.24 -> 3.0.0
- minor：2.3.24 -> 2.4.0
- patch：2.3.24 -> 2.3.25
- next：等同 patch
- custom：手动输入任意版本号
当前实现只计算并展示新版本号，不会写回配置文件
如需自动改 tauri.conf.json / Cargo.toml，需要后续扩展逻辑

3. 发布版本 `ugp publish`

cargo run -p ugp -- publish        # 交互选择 beta/stable/rollback
cargo run -p ugp -- publish --beta # 直接发布测试版
cargo run -p ugp -- publish --stable
cargo run -p ugp -- publish --rollback
cargo run -p ugp -- publish --beta --only-publish   # 只发布，不重新打包

流程（简化）：

读取 .ugp/config.toml，拿到：
- 安装包路径：install_package_path
- 发布路径：release_package_path
- 发布 URL：release_url
从 src-tauri/tauri.conf.json 中读取应用名称、版本号
从 install_package_path 下拷贝：
- MSI 安装包：{productName}_{version}_{arch}_zh-CN.msi
- 签名文件：同名 .msi.sig
生成 releases.json / releases_beta.json：
- notes 字段来自 README.md 渲染后的 HTML
- force_update 按发布类型设置
落盘到 ./.ugp/version 并按配置复制到网络共享目录
若为 stable，额外生成当前版本号对应的历史文件：
- ./.ugp/version/{version}.json

3.1 发布子命令参数

--beta
- 直接发布测试版（不弹选择菜单）
--stable
- 直接发布生产版（目前主要做确认提示，后续可扩展为生产环境发布流程）
--rollback
- 从历史版本中选择一个版本进行“信息回退”（仅回退 releases.json 相关信息，不动安装包）
--only-publish
- 与 --beta / --stable 搭配使用
- 默认 ugp publish 会先执行一次打包命令（详见下文构建命令），加上 --only-publish 后只做发布动作，不重新构建安装包

3.2 构建命令（UGP_BUILD_CMD）

ugp publish 在发布前需要有可用的安装包。构建安装包时的命令顺序为：

如果设置了环境变量 UGP_BUILD_CMD，优先执行，例如：

# Windows PowerShell 示例
$env:UGP_BUILD_CMD = "pnpm tauri build"
cargo run -p ugp -- publish --beta

# 或使用 npm
$env:UGP_BUILD_CMD = "npm run tauri -- build"
cargo run -p ugp -- publish --beta

# 或使用 cargo-tauri
$env:UGP_BUILD_CMD = "cargo tauri build"
cargo run -p ugp -- publish --beta

内部通过系统 shell 执行：
- Windows：cmd /C <UGP_BUILD_CMD>
- macOS/Linux：sh -lc '<UGP_BUILD_CMD>'
所以你在终端能直接跑通的命令，配置到 UGP_BUILD_CMD 一般都能正常执行。

如果未设置 UGP_BUILD_CMD，会按顺序自动尝试：
```
pnpm tauri build
npm run tauri -- build
cargo tauri build
```
找到第一个执行成功的命令即视为构建成功。

4. 查看版本历史 `get_version_history`

内部工具函数 generate::get_version_history() 会：

读取 ./.ugp/version 目录下所有 .json 文件
排除聚合文件：releases.json、releases_beta.json
使用 semver 解析并按版本大小排序（2.10.0 > 2.9.0）
返回 Vec<String>，例如：["1.3.0", "1.9.0", "2.0.0", "2.3.24"]

注意事项

运行路径
- 默认假设当前工作目录为仓库根目录
- tauri.conf.json 路径：./src-tauri/tauri.conf.json
- 发布配置路径：./.ugp/config.toml
文件命名约定
- 安装包：{productName}_{version}_{arch}_zh-CN.msi
- 签名文件：同名 .msi.sig
- 历史版本：.ugp/version/{version}.json
版本号格式
- 必须符合 x.y.z 语义化版本规范（如 2.3.24）
- ugp next 和版本历史排序都依赖此格式
发布前准备
- 确保 Tauri 应用已经打包完成，目标 MSI 及 .sig 存在
- 确认 .ugp/config.toml 中的网络路径有写权限
- 推荐在 CI 或专用发布机上运行 ugp，避免路径不一致
构建环境
- Windows：
  - 建议使用 PowerShell 或 CMD，确保 pnpm / npm / cargo 命令在当前 shell 下可用
  - 构建时会统一通过 cmd /C 执行命令，行为与手动在终端里输入一致
- macOS / Linux：
  - 需要在 sh 的环境下能找到相应命令（PATH 配置正确）
- 如遇到 “命令执行失败” 或 “未找到可用的构建命令” 错误，优先在终端单独跑一遍对应命令确认，并考虑显式设置 UGP_BUILD_CMD。

如需进一步扩展（例如自动写回版本、发布后自动推送 Git tag 等），可以在现有命令基础上新增子命令或扩展 publish/next 的行为。

ugp CLI 使用说明

顶层命令总览（ugp -h）

1. 初始化配置 ugp init

2. 计算下一个版本号 ugp next

3. 发布版本 ugp publish