ci-pub

ci-pub — 自动化发布预检与发布引擎

操作不变量

• 变更前置门槛：展示版本候选项并立即暂停当前轮次；未经人工明确授权，禁止修改清单、更新日志或 Git 历史。
• 自主上传边界：严格将执行范围限制在本地预检审计、清单更新和试运行验证；禁止自主上传软件包、推送标签或发布。
• 历史记录原子性：清单、更新日志和工作流更新必须严格包含在单个发布提交中（或 amend HEAD）；禁止创建脱离发布流程的杂务提交或未关联提交的发布标签。

执行协议

阶段 1：发现环境与发布设置

1. 发布策略与 CI 审计：
   • 检查 .github/workflows/ 中是否存在现有的发布/发布工作流（例如 publish.yml、release.yml）。识别已配置的触发机制：由标签驱动的 OIDC（refs/tags/*）、手动分发（workflow_dispatch），或不存在（由终端/命令行驱动）。
   • CI 初始化门槛（未配置 CI 时）：如果 .github/workflows/ 中没有发布工作流，指出未检测到自动化 CI，并提出从 references/workflow-single.yml 或 references/workflow-workspace.yml 初始化一个工作流（与发布原子提交）。
   • 阅读仓库发布文档和运行手册（doc/runbooks/*publish*.md、docs/*release*.md、CONTRIBUTING.md），提取项目特定的发布不变量和打包限制。
2. 拓扑结构与成员映射：
   • 单个软件包：根目录的 pubspec.yaml 不含 workspace: 指令。
   • Pub 工作区：根目录的 pubspec.yaml 包含 workspace:（要求 Dart SDK ^3.6.0，根目录的 publish_to: none）。运行 dart pub workspace list（或 fvm dart pub workspace list）以识别候选成员软件包并映射拓扑依赖顺序。
3. 远程与本地版本基线：
   • 查询 pub.dev API（curl -s https://pub.dev/api/packages/<pkg>）以确定远程当前版本（若返回 404，则标记为 UNPUBLISHED）。
   • 读取本地清单版本（grep '^version:' <pubspec.yaml>）。
   • 比较远程版本与本地版本以确定提案基线：未升级（Local == Remote）、工作树中已预先升级（Local > Remote）或首次发布（UNPUBLISHED）。

阶段 2：预检质量门槛

对目标发布范围运行格式检查（dart format --output=none --set-exit-if-changed .）、分析器检查（dart analyze --fatal-infos）、更新日志就绪检查和测试套件。如果任何验证失败，报告诊断结果并立即停止。

阶段 3：版本提案与暂停门槛

1. 评估目标软件包的变更范围（breaking、feat、fix）。
2. 提出发布方案：
   • 单个软件包：根据远程版本基线提出建议的 SemVer 候选版本（并在适用时提供可选的预发布预览版本）。
   • Pub 工作区：按拓扑顺序列出受影响软件包的发布矩阵，包含远程当前版本与本地版本、建议版本，以及下游约束级联变更。
   • 添加 CI 工作流：如果用户在阶段 1 选择初始化发布工作流，则将 .github/workflows/publish.yml 纳入建议的变更集。
3. 立即暂停当前轮次，等待用户选择版本并进行人工授权。

第 4 阶段：清单变更、试运行验证与交接

1. 清单与变更日志同步：获得用户批准后，同步目标 pubspec.yaml 清单、各软件包的 CHANGELOG.md 文件，以及种子 .github/workflows/publish.yml（如有请求）中的版本。
2. 原子发布提交：暂存已更新的文件，并修改 HEAD（git commit --amend --no-edit），或创建原子发布提交（git commit -m "chore(release): publish packages [...]"）。
3. 最后验证（试运行）：按拓扑顺序依次执行软件包管理器的发布试运行：
   • 单个软件包：dart pub publish --dry-run
   • Pub 工作区：对每个获批软件包执行 dart pub -C <package_dir> publish --dry-run。
   • 如果出现错误、警告或归档内容泄露，提供准确的故障诊断信息并立即停止。
4. 发布就绪报告与定制交接：
   • 提供试运行确认信息和拓扑发布顺序。
   • 根据第 1 阶段确认的发布设置定制交接说明：
     • 由 CI 驱动（推送标签）：提供与仓库标签模式完全匹配的 Git 标签命令（例如，单个软件包使用 v<version>，工作区使用 <package>-v<version>），指向发布提交 SHA，并提供推送标签的命令。
     • 终端/CMD：按拓扑顺序提供直接发布命令（dart pub publish / dart pub -C <package_dir> publish），并注明 pub.dev CDN 的传播窗口为 120 秒；参见 references/pub-workspace-workflow.md。