ci-pub

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

運用上の不変条件

• 変更前の承認ゲート：バージョン候補を提示したら、ただちにターンを終了します。人間から明示的な承認を得るまで、マニフェスト、変更履歴、Git の履歴を変更してはなりません。
• 自動アップロードの境界：実行範囲は、ローカルでの事前監査、マニフェストの更新、ドライラン検証に厳密に限定します。パッケージのアップロード、タグのプッシュ、自律的な公開を行ってはなりません。
• 履歴の原子性と整合性：マニフェスト、変更履歴、ワークフローの更新は、単一のリリースコミット内（または 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. リリース対象パッケージの変更範囲（破壊的変更、機能追加、修正）を評価します。
2. リリース案を提示します：
   • 単一パッケージ：リモートの基準値に基づいた推奨 SemVer 候補を提案します（該当する場合は、プレリリース候補も提示できます）。
   • Pub ワークスペース：影響を受けるパッケージ、リモートの公開済みバージョンとローカルバージョン、提案バージョン、下流の制約への波及を、トポロジカルな順序で一覧にしたリリースマトリックスを提示します。
   • CI ワークフローの追加：フェーズ 1 でユーザーが公開ワークフローの初期設定を選択した場合は、提案する変更に .github/workflows/publish.yml を含めます。
3. ただちにターンを終了します。ユーザーがバージョン案を選択または承認するまで、マニフェストや Git の履歴を変更してはなりません。

フェーズ 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 を参照）。