npm package: @huyooo/release
Description: Electron 应用发布 CLI：版本号更新 → 打包 → 上传 COS → 生成并上传 version.json
Author: huyooo
Latest version: 0.2.1

# @huyooo/release

Electron 应用发版 CLI：打包 → STS 安全上传 → 自动更新下载页。

## 原理

```
┌─────────────┐     ┌──────────────┐     ┌─────────────┐
│  release CLI │────▶│  ones-server │────▶│  腾讯云 COS  │
│  (开发机)    │     │  (API + DB)  │     │  (安装包存储) │
└─────────────┘     └──────────────┘     └─────────────┘
       │                   │                     │
       │  1. API Key 认证   │                     │
       │  2. 获取 STS 凭证  │                     │
       │  3. 用 STS 上传    │─────────────────────│
       │  4. 通知上传完成   │                     │
       │                   │                     │
       │                   │  DB: appReleases     │
       │                   │  (版本+平台+URL)     │
       │                   │                     │
┌─────────────┐            │                     │
│  前端下载页  │────────────│                     │
│  (官网)     │  POST /releases/latest           │
└─────────────┘  ← 返回最新版本下载信息           │
       │                                         │
       │  用户点击下载 ──────────────────────────▶│
       │                    直接从 CDN 下载安装包  │
```

**安全性**：CLI 不持有 COS 原始密钥，通过 ones-server 获取 STS 临时凭证（30 分钟有效，仅限指定目录），上传完成后凭证自动失效。

**存储路径**：
```
{appId}/releases/{version}/{platformId}/{原始文件名}
```
文件名保留 electron-forge 产出的原始命名（如 `Smart Finder.dmg`），方便用户识别。

## 快速开始

### 1. 安装

```bash
npm install -g @huyooo/release
```

### 2. 配置 API Key（一次性）

在 ones 管理后台创建 API Key，然后：

```bash
release config
# API Key ID:     ak_xxx
# API Key Secret: sk_xxx
```

凭证存储在 `~/.config/huyooo-release/config.json`。

### 3. 发版

```bash
# 主开发机：bump 版本号 + 打包上传
release bump patch && release build

# 其他平台机器：拉代码 + 打包上传
git pull && release build
```

完成后下载页自动更新（哪个平台上传了就显示哪个）。

## 命令

### `release bump [patch|minor|major]`

更新 `package.json` 版本号，git commit + tag + push。

```bash
release bump patch   # 1.0.0 → 1.0.1
release bump minor   # 1.0.0 → 1.1.0
release bump major   # 1.0.0 → 2.0.0
release bump         # 交互式选择
```

### `release build`

打包当前平台 → 用 STS 上传到 COS → 通知 ones-server 更新 DB。

```bash
release build                    # 用 default profile
release build --profile pixflow  # 用 pixflow profile
```

流程：
1. `electron-forge make` — 打包
2. 扫描 `out/make/` 找到 `.dmg`/`.zip`/`.exe`
3. 调 ones-server `getUploadToken` 获取 STS 临时凭证
4. 用 STS 上传到 COS（保留原始文件名）
5. 调 ones-server `uploadComplete` 更新版本记录

自动检测当前平台：
- macOS → 上传 `.dmg` + `.zip`
- Windows → 上传 `.exe`
- Linux → 上传 `.AppImage`

### `release [patch|minor|major]`

bump + build 一步完成（单平台快捷方式）。

```bash
release patch   # = release bump patch && release build
```

### `release config`

管理 API Key 凭证，支持多 profile。

```bash
release config                           # 配置 default
release config --profile pixflow         # 配置 pixflow
release config --show                    # 查看 default（打码）
release config --show --profile pixflow  # 查看 pixflow
release config --list                    # 列出所有 profile
```

### `release --dry-run`

预览模式，不真正执行。

```bash
release build --dry-run
release patch --dry-run
```

## 多平台发版

Electron 必须在各自平台打包，分步执行：

```bash
# 主开发机（Mac 或 Windows）
release bump patch    # 更新版本号，push tag
release build         # 打包当前平台，上传

# 其他平台机器
git pull              # 拉取最新代码（版本号已更新）
release build         # 打包当前平台，上传
```

| 步骤 | 在哪里跑 | 做什么 |
|------|---------|--------|
| `release bump patch` | 主开发机（一次） | 更新版本号 + push tag |
| `release build` | 每台机器各跑一次 | 打包 + 上传 + 更新 DB |

每次 `release build` 完成后，下载页自动多出对应平台。不需要额外的 "publish" 或 "finish" 步骤。

同一个版本重复上传是安全的——COS 文件覆盖，DB 记录更新。

## 多项目

每个项目用不同的 API Key（绑定不同 appId），通过 profile 区分：

```bash
# 配置
release config                     # smart-finder（default）
release config --profile pixflow   # pixflow

# 发版
cd smart-finder && release build                    # 用 default
cd pixflow && release build --profile pixflow        # 用 pixflow
```

也可以在 `package.json` scripts 里写死：

```json
{
  "scripts": {
    "release:start": "release bump patch && release build --profile pixflow",
    "release:build": "release build --profile pixflow"
  }
}
```

## ones-server API

CLI 调用 ones-server 的 3 个接口：

| 接口 | 认证 | 说明 |
|------|------|------|
| `POST /releases/getUploadToken` | API Key | 获取 STS 临时凭证，限指定目录 |
| `POST /releases/uploadComplete` | API Key | 上传完成，更新版本记录 |
| `POST /releases/latest` | 公开（app-id header） | 前端获取最新版本 |

## 前端接入

UI 组件从 `globalConfig` 自动读取 `appId` 和 `onesPrefixUrl`：

```vue
<DesktopDownloads title="桌面客户端" description="免费下载" :use-zip="true" />
<DownloadDropdown :use-zip="true" />
```

初始化时设置 `appId`：

```typescript
import { setGlobalConfig } from '@huyooo/ui'
setGlobalConfig({ appId: '6956135fb250d28c905f9254' })
```

`useZip` prop：
- `true` → 下载 ZIP（无签名时推荐，解压后右键打开）
- `false`/不传 → 下载 DMG/EXE（有签名时的正式安装体验）

## 开发

```bash
npm run dev    # 监听模式构建
npm run build  # 生产构建
npm test       # 运行测试
```

## License

MIT