ci-pub

ci-pub — 自動リリースの事前確認・公開エンジン

運用上の不変条件

• 変更前の承認ゲート：バージョン候補を提示したら、直ちにターンを終了します。人間から明確な承認を得ずに、マニフェスト、変更履歴、Git の履歴を変更することは禁止します。
• 自動アップロードの境界：実行範囲をローカルでの事前確認監査、マニフェストの更新、ドライランでの検証に厳密に限定します。パッケージのアップロード、タグのプッシュ、自律的な公開は禁止します。
• 履歴の原子性と整合性：マニフェスト、変更履歴、ワークフローの更新は、必ず単一のリリースコミット内（または HEAD の amend）にまとめます。独立した雑務コミットや、コミットに紐付かないリリースタグは禁止します。

実行プロトコル

フェーズ 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 主導（タグのプッシュ）：リポジトリのタグパターン（単一パッケージでは v<version>、ワークスペースでは <package>-v<version> など）に一致し、リリースコミットの SHA を指す正確な Git タグコマンドと、タグのプッシュコマンドを提示します。
     • ターミナル／CMD：直接公開するコマンドをトポロジカル順に提示します（dart pub publish／dart pub -C <package_dir> publish）。pub.dev CDN の反映に 120 秒かかることを明記してください（references/pub-workspace-workflow.md を参照）。