cli-forge-publish

cli-forge の公開

準拠した状態で生成された CLI スキルに、標準的なリリース自動化を導入する場合、新しいバージョンを準備する場合、または GitHub Release と複数パッケージの npm 公開を組み合わせたフローを実行する場合に、このステージを使用します。

目的

生成された cli-forge スキルのリリースパイプラインを管理します。

このステージでは、次のブートストラップから本番公開までのフローを担当します。

• メインパッケージとすべてのプラットフォームパッケージに対する、必須のローカル 事前公開 手順
• 後続の semantic-release イベントから実行する、リポジトリ標準の GitHub Release とプラットフォーム別 npm 公開の組み合わせ

本番リリース 1 回につき、次のものが作成されます。

• git タグ v<version> と GitHub Release（各ターゲットのアーカイブと sha256 を含む）
• ネイティブバイナリを含む、プラットフォーム別 npm パッケージ 6 個（<pkg>-darwin-arm64 ／ -darwin-x64 ／ -linux-arm64 ／ -linux-x64 ／ -win32-arm64 ／ -win32-x64）
• メイン npm パッケージ 1 個（JS シム、同じバージョンに固定された optionalDependencies）
• CHANGELOG.md のエントリーと chore(release): <version> [skip ci] コミット

すべての npm パッケージは、1 回の semantic-release 実行ですべて公開され、git タグおよび GitHub Release と同じバージョンを共有します。合計数は 1 + config.targets.length です（デフォルト：7）。

基準となるリファレンス

• ./instructions/release/skill-release-runbook.md
• ./planning-brief.md
• ./shared-planning-brief.md
• ./contracts/release-receipt.yml.tpl
• ./templates/

開始条件

#	確認項目	出典
1	validation-report.yml が存在し、最新であり、result == compliant または warning である	Validate
2	対象リポジトリのパスが明示的に指定されている	Router / User
3	要求された公開モードが明示されている	Router / User
4	npm パッケージの命名規約、CLI 名、スコープに関する決定が明示されている	User

このステージでは、スコープに関する決定が必須の入力です。メインパッケージ名と、メインパッケージおよびプラットフォームパッケージそれぞれのスコープポリシーを収集してください。メインパッケージとプラットフォームパッケージには異なるスコープを使用できますが、プラットフォーム名は引き続き、メインパッケージ名の本体に -<target-suffix> を付けて生成する必要があります。

必須入力

• 検証結果と来歴スナップショット（non_compliant、最新でない場合、または来歴が一致しない場合は公開を拒否）
• 公開モード：report_only、dry_run、prepublish、または live_release
• ソースプロジェクトのパス
• cliName — CLI バイナリ名
• mainPackageName — メインの npm パッケージ名（スコープを使用する場合はスコープのプレフィックスを含む）
• mainNpmScope — スコープなしの場合は null、メインパッケージにスコープを使用する場合はスコープ文字列
• platformNpmScope — スコープなしのプラットフォームパッケージの場合は null、別のスコープを使用する場合はスコープ文字列
• sourceRepository — GitHub 上の owner/repo

ワークフロー

1. 公開に固有の計画上の制約について、./planning-brief.md を読みます。
2. 受け取った validation-report.yml を確認します。検証に失敗している場合は続行せず、ここで検証を再実行しないでください。
3. 公開モードの操作を行う前に、検証の鮮度を確認します。
   • 現在の .cli-forge/design-contract.yml、.cli-forge/cli-plan.yml、ベースラインレシート（scaffold-receipt.yml または takeover-receipt.yml）、および任意の extend-receipt.yml を、validation-report.yml に記録された来歴スナップショットと照合します
   • テイクオーバーで採用されたベースラインの場合、レポートの来歴が現在の採用済みコントラクトとレシートのセットに完全に一致することを必須とします。集約された検証結果だけに依存しないでください
   • 必須のベースライン成果物が欠けている場合、レシートが異なる場合、または検証後にテイクオーバーで記録されたコントラクト／ベースラインが書き換えられている場合は、停止して Validate に戻します
4. まだ収集していない場合は、上記の入力をユーザーに尋ねます。モードが report_only の場合は、手順 7 に進みます。
5. スキルプロジェクトにリリース自動化アセットがない場合は、./templates/ の内容をプロジェクトのルートにコピーして採用し、インストール時に安全な dot-* リソースエイリアスを実際のドットで始まるターゲットパスに戻します（dot-releaserc.json -> .releaserc.json、dot-github/ -> .github/、npm/platforms/dot-gitkeep -> .gitkeep）。採用するアセットパックには Scaffold 段階のソーステンプレート（*.tpl）は含まれません。
6. 収集した入力を release/config.json と npm/main/package.json に反映します。release/config.json には mainPackageName、mainNpmScope、platformNpmScope を明示的に記録する必要があります。
7. ターゲットリポジトリが以下を備えていることを確認します。
   • GitHub ホストランナーで GitHub Actions が有効になっており、id-token: write が設定されている
   • npmjs.com で、メインパッケージと 6 つの各プラットフォームパッケージに npm の信頼された公開が設定されており、各エントリが release.yml を参照している
8. ./instructions/release/skill-release-runbook.md で定義されたモードの手順に従います。
   • report_only：準備状況のみを監査します。設定とリポジトリの状態を読み取り、ブロッカーと次のアクションを報告します。ファイルのコピー、プレースホルダーの入力、リポジトリの変更は一切行わないでください。
   • dry_run：ローカルで npm run release:rehearse を実行します。すべてのターゲットをビルドし、プラットフォームパッケージを同期し、それぞれに対して npm publish --dry-run を実行します。タグ、GitHub Release、実際の npm 公開は行われません。
   • prepublish：ローカルで npm run release:prepublish を実行します。専用のブートストラップ用プレリリースバージョンを使用して、すべてのプラットフォームパッケージとメインパッケージを実際に npm で公開します。ローカル認証がない場合は、対話形式の npm login のために一時停止し、検証 URL を提示して、ユーザーがブラウザーでの検証を完了した後にのみ続行します。
   • live_release：main にプッシュするか、workflow_dispatch を実行して、ターゲットリポジトリの .github/workflows/release.yml に一連の実行を最初から最後まで行わせます。このファイルは、インストーラー向けの安全なアセットパックリソース dot-github/workflows/release.yml から復元されたものです。設定されたパッケージセットのブートストラップ用 prepublish が完了するまで、live_release に進まないでください。
9. ./contracts/release-receipt.yml.tpl のテンプレートから .cli-forge/release-receipt.yml を生成します。

出力

• メイン npm パッケージ 1 つと N 個のプラットフォーム npm パッケージに対する、検証済みの prepublish ブートストラップ（prepublish の場合）
• アーカイブとチェックサムを含む、検証済みの GitHub Release（live_release の場合）
• 同一の本番バージョンで公開された、メイン npm パッケージ 1 つと N 個のプラットフォーム npm パッケージ（live_release の場合）
• 更新された CHANGELOG.md と main 上のリリースコミット
• .cli-forge/release-receipt.yml

終了ゲート

#	チェック
1	要求されたモードが実行されていること
2	report_only の場合：対象リポジトリにファイルが書き込まれていないこと
3	dry_run / prepublish / live_release の場合：アセットパックが採用され、内容が揃っていること
4	prepublish の場合：タグや GitHub Release を作成せずにブートストラップ用 npm プレリリースが完了していること
5	live_release の場合：バージョン、タグ、メインパッケージ、プラットフォームパッケージが一致していること
6	release-receipt.yml が生成されていること

ガードレール

• すべての npm パッケージ（メインおよびプラットフォーム）は、semantic-release が選択したバージョンを共有する必要があります。2 つのリリーススクリプトは、semantic-release のフックから ${nextRelease.version} を使用してこれを徹底します。
• ブートストラップの prepublish ステップでは、0.0.0-prepublish.N のような専用のプレリリースバージョンを使用する必要があります。これは本番リリースではありません。
• メインパッケージとプラットフォームパッケージで異なるのはスコープのみです。プラットフォームごとに任意のパッケージベース名を導入しないでください。
• 古い検証を回避しないでください。最後の検証レポート以降にコードベースが変更されている場合は、Validate に戻してください。
• 引き継ぎ時に採用されたリポジトリでは、鮮度チェックで validation-report.yml の集計ステータスやタイムスタンプだけでなく、現在のコントラクトとレシートのセットに対する来歴を検証する必要があります。
• npm/main/package.json#version を手動で更新したり、CHANGELOG.md のリリース項目を手動編集したり、semantic-release を介さずにタグを作成したりしないでください。
• 対話式の npm login の案内は、ローカルの prepublish に限ります。本番 CI の公開では、引き続き信頼されたパブリッシングを使用する必要があります。
• 対象リポジトリに dot-* エイリアス名を残さないでください。これらの名前は、このスキルパッケージ内でのみ使用され、.agents インストーラーがアセットを保持できるようにするものです。
• アセットパックの npm/platforms/ ディレクトリはリリース時に生成されます。.gitkeep プレースホルダーを除き、生成されたプラットフォームパッケージディレクトリをソース管理に含めないでください。

次のステップ

これは最終段階です。