shipup 0.2.0

package/docs/android-markets.md

@@ -0,0 +1,190 @@
+# 应用市场「素材 / 元数据」可更新能力与规格要求
+
+> **目的**：梳理各 Android 应用市场（华为 / 荣耀 / OPPO / vivo / 小米 / 三星 / 应用宝 / 魅族）通过**开放平台 API** 能更新哪些素材与元数据，以及每个渠道的**素材规格**（图标、截图、视频的格式 / 尺寸 / 大小）与**文案规则**（长度限制、能否用 emoji），为传包工具 shipup 规划「通用元数据更新」能力提供依据。
+>
+> **来源与可信度标注**：`[官]` = 渠道开放平台官方文档/审核规范；`[转]` = 第三方明确转述官方规范、多源一致；`[三]` = 第三方上架指南经验值；`[代]` = 现有对接代码实证；`[?]` = 各源冲突或未找到权威依据，需登录控制台实测。
+>
+> **字段名/规格已对 8 家官方文档逐一核实**（浏览器渲染直读）。素材的精确数值（标 `[三]` / `[?]`）仍以各渠道控制台上传表单为准。
+>
+> **实现状态（shipup 0.2.0）**：截图 / 应用名 / 一句话简介 / 长描述更新 + 图标按渠道压缩**已落地**（扩展 `upload`，按需生效）。各渠道字段名均已官方确认（详见第七节）。分类 / 年龄分级 / 视频 / 不换包更新 **暂未实现**。尚未做真实凭证沙箱联调。
+
+---
+
+## 一、各渠道「可通过 API 更新」能力矩阵
+
+下表为**各渠道 API 能力**：`✅` 支持　`❌` 不支持（需后台网页维护）　`❓` 待核实。「shipup 实现状态」见表下注。
+
+| 素材 / 元数据 | 华为 | 荣耀 | OPPO | vivo | 小米 | 三星 | 应用宝 | 魅族 |
+|---|:--:|:--:|:--:|:--:|:--:|:--:|:--:|:--:|
+| APK 安装包 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| 应用图标 | ✅ | ✅ | ✅ | ✅ | ✅必传 | ✅ | ✅ | ✅必传 |
+| 截图 / 介绍图 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| 更新说明 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| 应用名称 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅限改 | ✅ |
+| 一句话简介 / 推荐语 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| 应用简介 / 长描述 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| 隐私政策 URL | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ❓ | ✅ |
+| 分类 | ❌ | ❓ | ✅ | ✅ | ✅ | ❓ | ✅ | ✅ |
+| 年龄分级 | ❌后台 | ❓ | ✅ | ✅ | ❌后台 | ✅ | ❓ | ✅ |
+| 关键词 / 标签 | ❌ | ❌ | ❌ | ❌ | ✅keyWords | ❓ | ❓ | ✅keyword |
+| 宣传视频 | ✅ | ✅ | ✅ | ✅ | ✅后台 | △仅YouTube | ✅ | ❌ |
+| **不换包仅改元数据** | ✅* | ❓ | ✅ updm | ❌ | ❓ | ❓ | ✅ | ❌ |
+
+\* 华为：更新基本信息 / 语言描述 / 文件信息是各自独立的接口，理论上可不带新包再 `app-submit` 提审，但「无新包能否提审」官方未逐字确认，建议实测。OPPO 有独立的「更新资料」端点 `app/updm`（不新增版本）；应用宝 `update_app` 文档明确「也可仅更新基础信息，不更新文件」。vivo / 魅族的发布接口强制带新包。
+
+> **shipup 0.2.0 实现状态**：**已实现**（随包按需更新）—— 图标（按渠道压缩）、截图、应用名、一句话简介、长描述、更新说明，覆盖全部 8 渠道；荣耀曾因文档误判暂缺，现已补齐。**暂未实现** —— 分类 / 年龄分级 / 关键词 / 视频 / 隐私（除已有渠道）/「不换包仅改元数据」。
+
+**三条关键观察**：
+1. **截图 / 介绍图**：8 个渠道 API 全部支持，**shipup 0.2.0 已实现**（各渠道经各自上传接口换图，按需生效；不传则沿用线上）。
+2. **应用宝远比预期能打**：官方 `update_app` 支持图标、截图、简介、分类、视频，且支持不换包只改基础信息。此前"应用宝不用图标/截图"的判断是错的——**已在 shipup 0.2.0 补全**（图标 / 截图 / 应用名 / 简介）。
+
+---
+
+## 二、图标规格
+
+| 渠道 | 格式 | 尺寸(px) | 大小上限 | 形状 | API 是否必传 | 来源 |
+|---|---|---|---|---|---|---|
+| 华为 | PNG / WebP（部分 JPG） | **216×216**（也支持 512×512） | PNG ≤2MB / WebP ≤100KB | 正方形直角 | 可选 | [官] |
+| 荣耀 | PNG / JPG / JPEG | **512×512** | **≤200KB** | 直角 | 可选 | [官]（doc 101359 文件类型表） |
+| OPPO | PNG | 512×512 | <1MB | 直角，无圆角无黑边 | 可选 | [三] |
+| vivo | JPG / PNG | 256² 或 512² | **≤50KB**（审核口径，控制台或更宽） | 直角 | 可选 | [转] |
+| 小米 | PNG | 512×512 | <1MB | 清晰完整 | **必传** | [官]+[代] |
+| 三星 | PNG | 512×512 | ≤1MB(1024KB) | 正方形，可透明 | 可选 | [官] |
+| 应用宝 | PNG | 512×512 | **≤200KB** | 直角 | 可选 | **[官]** |
+| 魅族 | PNG | 512×512 | ≤1MB | 正方形，透明背景 | **必传** | [三]+[代] |
+
+> ⚠️ **尺寸/大小差异大**：华为 216² / 其余 512²（荣耀亦 512²，官方 doc 101359 已确认）；**应用宝、荣耀 ≤200KB、vivo ≤50KB** 比一般 1MB 严很多。shipup 已对图标按渠道大小上限自动压缩（超限逐步降尺寸）。形状都要求**直角原图**（圆角由系统裁切）。
+
+---
+
+## 三、截图 / 介绍图规格
+
+| 渠道 | 格式 | 尺寸(px) | 数量 | 单张大小 | 横竖屏 | 来源 |
+|---|---|---|---|---|---|---|
+| 华为 | PNG/JPG/JPEG（WebP） | 800×450 或 450×800（单边 320–3840） | 3–8 | ≤2MB（WebP ≤100KB） | 横/竖均可 | [官] |
+| 荣耀 | PNG/JPG/JPEG | 竖 1080×1920(fileType=3) / 横 1920×1080(fileType=2) | **3–5** | **≤5MB** | 横/竖（order 0-4） | [官] doc 101359 |
+| OPPO | JPG/PNG | 竖 1080×1920 / 横 1915×1080 | **3–5** | ≤1MB | 横竖均可（横版选填） | [三] |
+| vivo | JPG/PNG | 竖 1080×1920 / 横 1280×720·1920×1080 | **3–5** | ≤2MB | **必须全横或全竖** | [转] |
+| 小米 | PNG/JPG/JPEG/GIF/BMP/WEBP | 竖 1080×1920 / 横 1920×1080 | **≥3**（游戏 ≥4） | ≤5MB | 横/竖；平板另传一套 | [官]+[三] |
+| 三星 | JPG/PNG | 每边 320–3840，长宽比 ≤2:1 | **≥4**（最多展示 8） | ❓（移动端未明确） | 横/竖 | [官] |
+| 应用宝 | JPG/PNG | 建议 1080×1920，最小 320×480 | **4–5** | ≤1M | 所有图宽高须一致 | **[官]** |
+| 魅族 | JPG（也支持 PNG） | 800×1280 / 1080×1800 / 1152×1920 / 1536×2560 等（比例 1:1.6~1.7） | ❓ | **≤5MB** | 竖/横 | [三] |
+
+> 共性：截图须为真机/自制效果图，**不得含他牌手机外观、他家商店水印、状态栏通知图标、黑白边、"敬请期待"占位**。
+
+---
+
+## 四、文案长度限制
+
+| 渠道 | 应用名称 | 一句话简介 / 推荐语 | 应用简介 / 长描述 | 更新说明 | 来源 |
+|---|---|---|---|---|---|
+| 华为 | ≤15 汉字 / 30 字符 | briefInfo **≤80 字符**（建议 ≤25） | appDesc **≤8000 字符** | newFeatures **≤500 字符** | [官] |
+| 荣耀 | ≤15 汉字 / 30 字符 | briefIntro **≤80 字符** | intro **≤8000 字符** | newFeature **≤500 字符** | [官] doc 101359 |
+| OPPO | ≤15 汉字 / 30 英文（副标题 ≤10 字） | summary **≤13 字符，禁标点/空格** | detail_desc **≥20 字** | update_desc **≥5 字** | [三] |
+| vivo | 名称+副标题 ≤15 汉字 / 30 英文 | simpleDesc **5–16 汉字** | detailDesc **≥50 字** | updateDesc **≥5 字** | [转] |
+| 小米 | 网页 ≤20 字符 / 手机端显示名 ≤8 汉字 | brief **≤17 汉字 / 34 字符，句末勿标点** | desc 无明确上限 | updateDesc 不得为空 / 不与上版相同 | [官] |
+| 三星 | appTitle **100 字节**（中国区 ≤33 汉字） | shortDescription **40 字节（约 13 汉字）** | longDescription **4000 字节** | newFeature **4000 字节** | [官] |
+| 应用宝 | ≤20 汉字 / 40 字符（**1 年限改 2 次**，改后需重传软著） | ≤15 字 | 60–500 字 | feature ≤500 字符（存疑） | [官]限改 / [三]字数 |
+| 魅族 | **≤10 中文 / 20 英文** | recommendDesc ❓ | appDesc **100–1000 字符** | verDesc ❓ | [官] |
+
+> ⚠️ **三星按 UTF-8 字节计**（1 汉字 = 3 字节、1 emoji = 4 字节），`shortDescription` 仅 40 字节≈13 个汉字，很短。
+> ⚠️ **长描述上限差异巨大**：华为 8000 字符 vs 魅族 1000 字符 vs OPPO/vivo 只给下限。做通用更新时同一份长文案不能无脑发所有渠道，需按渠道截断/校验。
+
+---
+
+## 五、emoji 与文案格式规则
+
+**结论：应用名称几乎所有渠道都明确禁止 emoji / 特殊符号；正文（简介 / 更新说明）普遍"无明确允许"，建议一律不用 emoji。**
+
+| 渠道 | 应用名称 | 简介 / 更新说明正文 | 来源 |
+|---|---|---|---|
+| 华为 | 禁 emoji / 特殊符号（`* & - ( )` 等） | 无明文；建议纯文本，禁极限词，不支持 HTML | [官]+[三] |
+| 荣耀 | 禁特殊字符 `# * & - ( )`、占位符、乱码（emoji 视同禁止） | 无明文；建议不用 emoji | [官] |
+| OPPO | 禁破折号/空格/星号等特殊符号 | summary 禁标点空格→等于禁 emoji；正文无明文，建议不用 | [三] |
+| vivo | **仅限汉字/数字/字母 + "+"**；禁 emoji/特殊符号 | 一句话简介标点受限（仅逗号/感叹/顿号/问号/空格）；正文不建议 emoji | [转] |
+| 小米 | 禁特殊符号（`# * &` 等） | 无明文；建议避免 emoji 与 `#*&` | [官] |
+| 三星 | 中国区**仅允许** `+ ( ) _ : -`；其余符号/emoji 禁 | 无明文；注意 emoji 占 4 字节快速吃额度 | [官] |
+| 应用宝 | 禁特殊符号 / 空格 | 简介禁装饰性符号（★、- 等）；emoji 无官方允许，建议禁用 | [三] |
+| 魅族 | 禁 `@ # ￥ % & *` 等特殊字符（emoji 基本不可用） | 无明文；建议规避 | [官] |
+
+---
+
+## 六、宣传视频规格
+
+| 渠道 | 是否支持 | 格式 | 大小 | 时长 | 尺寸 | 来源 |
+|---|---|---|---|---|---|---|
+| 华为 | ✅（1–3 个） | MOV / MP4 | ≤500MB | 15s–2min | 横 1280×720 / 竖 720×1280 | [官] |
+| 荣耀 | ✅（弱确认） | ❓ | ❓ | ❓ | 16:9 / 9:16 | [官弱] |
+| OPPO | ✅（选填） | MP4 | <500MB | ❓ | ❓ | [三] |
+| vivo | ✅ | MP4 / MOV | ≤500MB | 15s–2min | 1080×1920（9:16）；封面 ≥450×800 ≤2MB | [三] |
+| 小米 | ✅（后台手动） | 多格式（mp4/mov/mkv/avi…） | ❓ | 应用 15–30s / 游戏 15–90s | 横版（禁竖屏黑边） | [官]+[三] |
+| 三星 | △ 仅 YouTube 外链 | — | — | — | — | [官]（中国区不可用） |
+| 应用宝 | ✅ | MP4（存疑） | ❓ | ~20–30s（存疑） | 竖 1080×1920（存疑） | [三] |
+| 魅族 | ❌ 发布接口无视频字段 | — | — | — | — | [代] |
+
+---
+
+## 七、官方核实结果与字段落地
+
+各渠道字段名均已对官方文档逐一核实（浏览器渲染），并落到 shipup 0.2.0：
+
+| 渠道 | 截图 | 文案字段（应用名 / 一句话 / 长描述） | 核实来源 |
+|---|---|---|---|
+| 应用宝 | `snapshots_file_serial_number`（`get_file_upload_info` file_type=`img`，COS 上传，`|` 分隔） | `app_name`(+`modify_app_name_reason`) / `one_word_summary` / `introduce` | 官方 API `iwiki/4015262492` |
+| 华为 | `app-file-info` fileType=2 + `imgShowType`（整组替换） | `appName` / `briefInfo`(≤80) / `appDesc`(≤8000)，走 `app-language-info` | 官方 Publishing API |
+| 荣耀 | `fileType=3`(纵向 1080×1920)，3–5 张 ≤5MB，按 `order 0-4` 绑定 | `appName` / `briefIntro`(≤80) / `intro`(≤8000)，走 `update-language-info` | 官方 doc 101359 |
+| 小米 | `screenshot_1..4`（multipart，SIG 同序加 md5） | `appName` / `brief`(≤17汉字) / `desc`，走 `dev/push.appInfo` | 官方 dev.mi.com |
+| vivo | `app.upload.screenshot` → `screenshot`（流水号逗号分隔，3-5 张） | `app_name` / `simpleDesc` / `detailDesc`(50-1000) | 官方 doc/343 |
+| 三星 | `screenshots`=`[{screenshotKey: fileKey, reuseYn:false}]` | `appTitle` / `shortDescription`(40字节) / `longDescription`(4000字节) | 官方 Content Publish API |
+| 魅族 | `screenShots`=`List<String>`（`/image/upload` 得 destFileName） | `appName` / `recommendDesc` / `appDesc`(100-1000) | 官方 doc/333 |
+| OPPO | `pic_url`（`get-upload-url` type=photo 上传，竖版） | `app_name` / `summary`(≤13) / `detail_desc`(≥20) | working 集成 + 官方端点 |
+
+### 图标行为（已修 + 压缩）
+- 官方语义：华为/OPPO/vivo 图标可选（不传 = 保留线上）；小米/魅族每次必传。
+- shipup 0.2.0：可选渠道默认不动图标、小米/魅族要求 `--icon`，且**按渠道大小上限自动压缩**（vivo ≤50KB、应用宝/荣耀 ≤200KB）→ 与官方语义一致、不再超限。
+
+### 暂未实现（API 支持，后续可补）
+- **分类 / 年龄分级 / 关键词 / 视频**：部分渠道支持（见矩阵），本期未接。
+- **不换包仅改元数据**：✅ 应用宝（仅基础信息）、OPPO（`app/updm`）、华为（结构上支持，待实测）；❌ vivo / 魅族（发布接口必带新包）；❓ 小米 / 三星 / 荣耀。本期统一走「随包更新」。
+
+---
+
+## 八、落地情况（shipup 0.2.0）与后续
+
+**已落地**：
+1. ✅ **扩展 `upload`**：新增 `--screenshot`（多张）/`--app-name`/`--summary`/`--description`，随包按需更新，8 渠道分别调各自接口。
+2. ✅ **应用宝补全**：从「仅 apk+feature」扩到图标 / 截图 / 应用名 / 简介。
+3. ✅ **图标按渠道压缩**：尺寸 + 大小上限内置（`src/adapters/android/specs.ts`），超限自动降尺寸。
+4. ✅ **规格校验**：文案长度 `warnIfTooLong` 告警（注意三星按字节）。
+
+**后续可补**：
+- 分类 / 年龄分级 / 关键词 / 视频更新（部分渠道 API 支持）。
+- 「不换包仅改元数据」（应用宝 / OPPO `app/updm` / 华为）。
+- emoji 过滤开关 + 应用名「禁特殊符号」硬校验（当前仅告警）。
+- **真实凭证沙箱联调**：现有实现按官方文档「最佳努力」，未经真机回包验证（整个 shipup 含 iOS 都未做）。
+
+---
+
+## 附：调研来源与可信度
+
+**字段名/接口结构**：8 家均已**官方文档直读核实**（浏览器渲染）：
+
+| 渠道 | 官方来源（浏览器直读） |
+|---|---|
+| 应用宝 | API 文档 `wikinew.open.qq.com/iwiki/4015262492` |
+| 华为 | Publishing API `app-file-info` / `app-language-info` |
+| 三星 | Content Publish API reference（screenshots 结构） |
+| 小米 | dev.mi.com 自动发布接口 `pId=1134`（appInfo 字段） |
+| vivo | dev.vivo.com.cn `doc/343`（app.sync.update.app 字段） |
+| 荣耀 | developer.honor.com `doc/guides/101359`（PubLanguageInfo + 文件类型表） |
+| 魅族 | open.flyme.cn `docs?id=333`（publish 字段 + screenShots 类型） |
+| OPPO | open.oppomobile.com 官方能力说明与公开端点 |
+
+**素材精确数值**：标 `[官]` 已核实；标 `[三]`/`[转]`/`[?]` 仍为第三方/转述，以渠道控制台为准。
+
+### 仍待实测 / 未定的项
+- **真实凭证沙箱联调**（最关键）：所有渠道的请求/签名/字段均未经真机回包验证。
+- OPPO `pic_url` 多图序列化格式（逗号 vs JSON 数组）、视频时长/尺寸。
+- vivo 图标大小上限（审核规范 50KB vs 控制台或更宽）。
+- 应用宝 / 小米 改 `app_name` 是否触发改名审核流程；emoji 明确政策。
+- 「不换包仅改元数据」各渠道是否真能提审（应用宝 / OPPO / 华为）。

package/docs/credentials.md

@@ -0,0 +1,72 @@
+# Credentials
+
+The default credential file is `~/.config/shipup/credentials.yaml`. Override it
+with `SHIPUP_CREDS` or `--creds <path>`. A single file may contain `android`,
+`harmony`, `huawei`, and `ios` sections; a provider-only file without the outer
+section is also accepted by Android and iOS commands.
+
+Values can be literal strings, `${ENVIRONMENT_VARIABLE}` references, or
+`@relative/file` references resolved from the credential file directory.
+
+## Android multi-market
+
+```yaml
+android:
+  package_name: com.example.app
+  channels:
+    huawei:  { app_id: "...", client_id: ${HW_ID}, client_secret: ${HW_SECRET} }
+    honor:   { app_id: "...", client_id: ${HONOR_ID}, client_secret: ${HONOR_SECRET} }
+    oppo:    { app_id: "...", client_id: ${OPPO_ID}, client_secret: ${OPPO_SECRET} }
+    vivo:    { app_id: "...", access_key: ${VIVO_AK}, access_secret: ${VIVO_SK} }
+    xiaomi:  { user_name: ${MI_USER}, password: ${MI_PASSWORD}, rsa_modulus: ${MI_RSA} }
+    samsung: { app_id: "...", service_account: ${SS_ACCOUNT}, private_key: "@./samsung.pem" }
+    qq:      { app_id: "...", user_id: "...", access_secret: ${QQ_SECRET} }
+    meizu:   { access_key: ${MZ_AK}, access_secret: ${MZ_SK} }
+```
+
+Only channels selected by `--upload` or `--channel` are validated.
+
+## HarmonyOS and Huawei compatibility commands
+
+```yaml
+harmony:
+  app_id: "..."
+  package_name: com.example.app
+  service_account: "@./agc-service-account.json"
+
+huawei:
+  app_id: "..."
+  package_name: com.example.app
+  service_account: "@./agc-service-account.json"
+```
+
+These commands accept an AppGallery Connect service account or API client
+credentials. The `shipup android ... huawei` adapter instead uses the Android
+market credentials under `android.channels.huawei`.
+
+## App Store Connect
+
+```yaml
+ios:
+  app_id: "..."
+  bundle_id: com.example.app
+  issuer_id: ${ASC_ISSUER_ID}
+  key_id: ${ASC_KEY_ID}
+  private_key: "@./AuthKey_XXXXXXXXXX.p8"
+  team_id: ${APPLE_TEAM_ID}
+```
+
+`app_id` is optional when commands receive `--bundle-id`. `team_id` is used by
+upload workflows that require it.
+
+## Storage rules
+
+Keep credentials and referenced key files outside application repositories:
+
+```bash
+chmod 600 ~/.config/shipup/credentials.yaml
+chmod 600 ~/.config/shipup/*.pem ~/.config/shipup/*.p8
+```
+
+`shipup` warns about group/world-readable credential files on Unix systems.
+Use the minimum provider role required for the selected command.

package/docs/providers.md

@@ -0,0 +1,60 @@
+# Provider behavior
+
+## HarmonyOS AppGallery
+
+`harmony upload` validates `pack.info` when present, obtains an OBS upload URL,
+streams the `.app`, registers it, and normally waits for compilation analysis.
+`harmony submit` supports immediate, scheduled, and phased submission.
+`harmony status` normalizes AppGallery release states.
+
+## Android multi-market
+
+`android upload` accepts one or more `--upload channel=apk` values and isolates
+failures per channel. The supported channel names are:
+
+| Channel | Store | Upload | Status | Optional metadata |
+|---|---|---:|---:|---|
+| `huawei` | Huawei AppGallery | yes | yes | icon, screenshots, name, summary, description, release notes |
+| `honor` | Honor App Market | yes | yes | icon, screenshots, name, summary, description, release notes |
+| `oppo` | OPPO App Market | yes | yes | icon, screenshots, name, summary, description, release notes |
+| `vivo` | vivo App Store | yes | yes | icon, screenshots, name, summary, description, release notes |
+| `xiaomi` | Xiaomi App Store | yes | yes | icon, screenshots, name, summary, description, release notes |
+| `samsung` | Samsung Galaxy Store | yes | yes | icon, screenshots, name, summary, description, release notes |
+| `qq` | Tencent MyApp | yes | yes | icon, screenshots, name, summary, description, release notes |
+| `meizu` | Meizu App Store | yes | yes | icon, screenshots, name, summary, description, release notes |
+
+Most Android market upload APIs submit or publish as part of upload; they do
+not provide a universal upload-only draft operation. `--submit-review` is an
+explicit intent marker, and the CLI prints a warning when it is omitted.
+
+Package name and version metadata are read from the APK unless supplied with
+`--version-name`, `--version-code`, and credentials. Native ABI contents are
+inspected for channels that distinguish 32-bit and 64-bit packages.
+
+Icons use `--icon` when supplied. Otherwise, channels that require a new icon
+use `aapt`/`aapt2` to select the highest-density raster launcher icon from the
+APK. Images are resized and compressed to provider limits. Screenshots and text
+metadata are updated only when their corresponding options are present.
+Detailed constraints are listed in [Android market capabilities](android-markets.md).
+
+## Huawei compatibility command
+
+`huawei upload|status` preserves the original service-account-oriented Huawei
+workflow. New multi-market automation should normally use
+`shipup android ... --upload huawei=...` so it can share orchestration and
+metadata options with other Android markets.
+
+## App Store Connect
+
+`ios upload` uploads through `xcrun altool` and can continue into submission.
+`ios submit` waits for a valid existing build, creates or reuses the App Store
+version, writes localizations, attaches the build, and submits the review.
+`--bundle-id` can resolve the numeric App ID automatically.
+
+`ios status` normalizes App Store state and includes phased-release state when
+available. `ios release` supports manual release, starting phased release,
+completing it immediately, pausing, and resuming. Repeated phased-release
+commands are guarded for idempotency.
+
+iOS upload requires macOS and Xcode. HTTP-only status, submission, and release
+commands run wherever the supported Node.js runtime is available.

package/lib/common.mjs

@@ -0,0 +1,265 @@
+// shipup 共享基础设施：错误/退出码、凭证加载（YAML 子集 + 三形态值）、
+// HTTP（GET 幂等重试）、AGC 鉴权（Service Account PS256 JWT / API 客户端 token）、zip 读取。
+import { createSign, constants as cryptoConstants } from "node:crypto";
+import { readFileSync, existsSync, statSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { inflateRawSync } from "node:zlib";
+
+export const ExitCode = { OK: 0, FAIL: 2, USAGE: 3, CREDS: 4, MISSING_INPUT: 5, TIMEOUT: 124 };
+
+export class CliError extends Error {
+  constructor(exitCode, message, errorCode = "") {
+    super(message);
+    this.exitCode = exitCode;
+    this.errorCode = errorCode;
+  }
+}
+
+export const log = (...a) => console.error(...a);
+export const b64url = (buf) => Buffer.from(buf).toString("base64url");
+
+/** Remove credentials and long opaque values before provider output reaches logs. */
+export function redactText(value) {
+  return String(value ?? "")
+    .replace(/-----BEGIN [^-]+-----[\s\S]*?-----END [^-]+-----/g, "<redacted-private-key>")
+    .replace(/(authorization\s*[:=]\s*)(?:bearer\s+)?[^\s,}\]]+/gi, "$1<redacted>")
+    .replace(/("?(?:access_token|client_secret|private_key|authCode|token)"?\s*[:=]\s*")([^"]+)(")/gi, "$1<redacted>$3")
+    .replace(/\b[A-Za-z0-9_-]{80,}\b/g, "<redacted-opaque-value>");
+}
+
+/** Provider URLs may contain app identifiers, signed query strings, or upload tokens. */
+export function redactUrl(value) {
+  try {
+    const url = new URL(value);
+    return `${url.origin}${url.pathname}`;
+  } catch {
+    return "<redacted-url>";
+  }
+}
+
+// ---------- 凭证 ----------
+
+// 值三形态：@文件 → 读文件内容；${ENV} → 环境变量；否则字面量
+export function resolveValue(raw, baseDir) {
+  if (raw == null) return raw;
+  if (raw.startsWith("@")) {
+    const p = resolve(baseDir, raw.slice(1));
+    if (!existsSync(p)) throw new CliError(ExitCode.CREDS, `@文件不存在: ${p}`);
+    return readFileSync(p, "utf8").trim();
+  }
+  const m = raw.match(/^\$\{(\w+)\}$/);
+  if (m) {
+    const v = process.env[m[1]];
+    if (!v) throw new CliError(ExitCode.CREDS, `环境变量未设置: ${m[1]}`);
+    return v;
+  }
+  return raw;
+}
+
+// 极简 YAML 子集：两级嵌套（平台段 → key: value）+ 注释。够用即可，不引依赖。
+function parseYamlSections(text) {
+  const sections = {};
+  let current = null;
+  for (const line of text.split("\n")) {
+    const noComment = line.replace(/(^|\s)#.*$/, "");
+    if (!noComment.trim()) continue;
+    const indented = /^\s/.test(noComment);
+    const m = noComment.trim().match(/^([\w.-]+)\s*:\s*(.*)$/);
+    if (!m) continue;
+    let value = m[2].trim();
+    if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+      value = value.slice(1, -1);
+    }
+    if (!indented && !value) {
+      current = m[1];
+      sections[current] = {};
+    } else if (indented && current) {
+      if (value) sections[current][m[1]] = value;
+    } else if (!indented && value) {
+      // 顶层散键：归入 _flat（单平台旧格式兼容）
+      (sections._flat ??= {})[m[1]] = value;
+    }
+  }
+  return sections;
+}
+
+/** 读 creds YAML 并取指定平台段，值全部按三形态解析。 */
+export function loadPlatformCreds(credsPath, platform) {
+  if (!existsSync(credsPath)) throw new CliError(ExitCode.CREDS, `凭证文件不存在: ${credsPath}`);
+  if (process.platform !== "win32") {
+    const mode = statSync(credsPath).mode & 0o777;
+    if ((mode & 0o077) !== 0) log(`警告：凭证文件权限为 ${mode.toString(8)}，建议 chmod 600 ${credsPath}`);
+  }
+  const baseDir = dirname(resolve(credsPath));
+  const sections = parseYamlSections(readFileSync(credsPath, "utf8"));
+  const section = sections[platform] ?? sections._flat;
+  if (!section || Object.keys(section).length === 0) {
+    throw new CliError(ExitCode.CREDS, `凭证文件缺少 ${platform}: 段（见 creds.example.yaml）`);
+  }
+  const creds = { _baseDir: baseDir };
+  for (const [k, v] of Object.entries(section)) creds[k] = resolveValue(v, baseDir);
+  return creds;
+}
+
+/** 解析 AGC Service Account 凭据（支持 JSON 内容或文件路径），校验必要字段。 */
+export function loadServiceAccount(creds) {
+  let jsonText = creds.service_account;
+  if (!jsonText.trimStart().startsWith("{")) {
+    const p = resolve(creds._baseDir, jsonText);
+    if (!existsSync(p)) throw new CliError(ExitCode.CREDS, `service_account 文件不存在: ${p}`);
+    jsonText = readFileSync(p, "utf8");
+  }
+  let sa;
+  try {
+    sa = JSON.parse(jsonText);
+  } catch {
+    throw new CliError(ExitCode.CREDS, "service_account 不是合法 JSON（应为 AGC 下载的 *private.json 凭据文件）");
+  }
+  for (const field of ["key_id", "private_key", "sub_account"]) {
+    if (!sa[field]) throw new CliError(ExitCode.CREDS, `service_account JSON 缺少 ${field}`);
+  }
+  return sa;
+}
+
+// ---------- HTTP ----------
+
+export function remainingMs(deadline) {
+  const left = deadline - Date.now();
+  if (left <= 0) throw new CliError(ExitCode.TIMEOUT, "总超时（--timeout）已到");
+  return left;
+}
+
+export function sleep(ms, deadline) {
+  return new Promise((r) => setTimeout(r, Math.min(ms, remainingMs(deadline))));
+}
+
+export async function fetchJson(url, init, deadline, { retries = 0 } = {}) {
+  for (let attempt = 0; ; attempt++) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), Math.min(remainingMs(deadline), 60_000));
+    try {
+      const res = await fetch(url, { ...init, signal: controller.signal });
+      const text = await res.text();
+      if (!res.ok && (res.status >= 500 || res.status === 429) && attempt < retries) {
+        await sleep(1000 * (attempt + 1), deadline);
+        continue;
+      }
+      if (!res.ok) {
+        throw new CliError(
+          ExitCode.FAIL,
+          `HTTP ${res.status} ${redactUrl(url)}\n${redactText(text).slice(0, 500)}`,
+          String(res.status),
+        );
+      }
+      try {
+        return text ? JSON.parse(text) : {};
+      } catch {
+        throw new CliError(ExitCode.FAIL, `非 JSON 响应 ${redactUrl(url)}: ${redactText(text).slice(0, 300)}`);
+      }
+    } catch (e) {
+      if (e instanceof CliError) throw e;
+      if (attempt < retries) {
+        await sleep(1000 * (attempt + 1), deadline);
+        continue;
+      }
+      throw new CliError(
+        e.name === "AbortError" ? ExitCode.TIMEOUT : ExitCode.FAIL,
+        `请求失败 ${redactUrl(url)}: ${redactText(e.message)}`,
+      );
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+}
+
+// ---------- AGC 鉴权（harmony + huawei 共用）----------
+
+export const AGC_API_BASE = "https://connect-api.cloud.huawei.com/api";
+const SA_TOKEN_AUD = "https://oauth-login.cloud.huawei.com/oauth2/v3/token";
+
+// Service Account：PS256 自签 JWT，直接作为 Bearer（无需 token 交换）
+export function serviceAccountAuth(sa) {
+  const iat = Math.floor(Date.now() / 1000);
+  const header = b64url(JSON.stringify({ kid: sa.key_id, typ: "JWT", alg: "PS256" }));
+  const payload = b64url(JSON.stringify({ aud: SA_TOKEN_AUD, iss: sa.sub_account, exp: iat + 3600, iat }));
+  const signer = createSign("RSA-SHA256");
+  signer.update(`${header}.${payload}`);
+  const signature = signer.sign({
+    key: sa.private_key,
+    padding: cryptoConstants.RSA_PKCS1_PSS_PADDING,
+    saltLength: cryptoConstants.RSA_PSS_SALTLEN_DIGEST,
+  });
+  return { Authorization: `Bearer ${header}.${payload}.${b64url(signature)}` };
+}
+
+/** 返回 AGC 请求鉴权头：优先 Service Account，回落 API 客户端（48h token + client_id 头）。 */
+export async function agcAuth(creds, deadline) {
+  if (creds.service_account) return serviceAccountAuth(loadServiceAccount(creds));
+  if (creds.client_id && creds.client_secret) {
+    const res = await fetchJson(`${AGC_API_BASE}/oauth2/v1/token`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ grant_type: "client_credentials", client_id: creds.client_id, client_secret: creds.client_secret }),
+    }, deadline);
+    if (!res.access_token) {
+      throw new CliError(
+        ExitCode.CREDS,
+        `获取 token 失败: ${redactText(JSON.stringify(res.ret ?? { error: "missing access_token" }))}`,
+        String(res.ret?.code ?? ""),
+      );
+    }
+    return { Authorization: `Bearer ${res.access_token}`, client_id: creds.client_id };
+  }
+  throw new CliError(ExitCode.CREDS, "凭证需要 service_account（推荐）或 client_id + client_secret 二选一");
+}
+
+/** AGC 业务接口：拼 query、校验 ret.code===0；GET 幂等自动重试，写操作不重试。 */
+export async function agc(method, path, { auth, query, body }, deadline) {
+  const qs = query ? "?" + new URLSearchParams(query).toString() : "";
+  const res = await fetchJson(`${AGC_API_BASE}${path}${qs}`, {
+    method,
+    headers: { ...auth, "Content-Type": "application/json" },
+    body: body ? JSON.stringify(body) : undefined,
+  }, deadline, { retries: method === "GET" ? 2 : 0 });
+  if (res.ret && Number(res.ret.code) !== 0) {
+    throw new CliError(ExitCode.FAIL, `AGC 接口错误 ${path}: [${res.ret.code}] ${res.ret.msg}`, String(res.ret.code));
+  }
+  return res;
+}
+
+// ---------- zip 读取（.app 的 pack.info 等）----------
+
+/** 从 zip 字节中读取指定 entry 的内容（Buffer），找不到/不支持返回 null。 */
+export function readZipEntry(buf, entryName) {
+  try {
+    let eocd = -1;
+    for (let i = buf.length - 22; i >= Math.max(0, buf.length - 22 - 65536); i--) {
+      if (buf.readUInt32LE(i) === 0x06054b50) { eocd = i; break; }
+    }
+    if (eocd < 0) return null;
+    const total = buf.readUInt16LE(eocd + 10);
+    let off = buf.readUInt32LE(eocd + 16);
+    if (off === 0xffffffff) return null; // zip64 不支持，fail-soft
+    for (let n = 0; n < total; n++) {
+      if (buf.readUInt32LE(off) !== 0x02014b50) return null;
+      const method = buf.readUInt16LE(off + 10);
+      const compSize = buf.readUInt32LE(off + 20);
+      const nameLen = buf.readUInt16LE(off + 28);
+      const extraLen = buf.readUInt16LE(off + 30);
+      const commentLen = buf.readUInt16LE(off + 32);
+      const localOff = buf.readUInt32LE(off + 42);
+      const name = buf.toString("utf8", off + 46, off + 46 + nameLen);
+      if (name === entryName) {
+        const lNameLen = buf.readUInt16LE(localOff + 26);
+        const lExtraLen = buf.readUInt16LE(localOff + 28);
+        const dataStart = localOff + 30 + lNameLen + lExtraLen;
+        const raw = buf.subarray(dataStart, dataStart + compSize);
+        return method === 8 ? inflateRawSync(raw) : Buffer.from(raw);
+      }
+      off += 46 + nameLen + extraLen + commentLen;
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}