package-cascade

Package Cascade

公開済みパッケージへの変更を依存関係グラフ上に伝播させます。これを参照するすべてのパッケージ（ComponentModule）について、参照先を再固定して再公開します。これを再帰的に行い、アプリケーションに到達したら停止します（アプリケーションは古い状態として報告し、自動公開は行いません）。このスキルは、dxs source cascade コマンドを使ったシンプルな対話型オーケストレーションです。

必須の事前知識

• ../datex-studio-shared/branch-setup.md — ブランチと接続の選択
• references/cascade-workflow.md — 正確な dxs コマンドを含むフェーズごとの手順
• references/plan-schema.md — カスケード計画の JSON 形式
• references/interaction-patterns.md — ツリーの表示、選択・除外のプロンプト、進捗の説明
• references/troubleshooting.md — 公開の失敗、ロック、競合、再開

使用する場合／しない場合

元のパッケージがすでに公開済みで、その利用側も更新したい場合に使用します。変更を加え、コミットし、元のパッケージを公開するのはユーザーです。このスキルは、公開済みバージョン以降の処理を引き継ぎます。

次の場合は使用しないでください。パッケージ自体の変更を作成する場合（component-creator スキルを使用）、単一ブランチの呼び出し元を分析する場合（impact-analysis を使用）、または依存先を調べる場合（dxs source deps を使用）。

役割分担（この境界を越えないでください）

決定性を担うのはすべて CLI です。グラフの走査、トポロジカル順序の決定、推移的な参照の再構築、競合・循環の検出は、dxs source cascade plan と dxs source reference set が担当します。このスキルが担当するのは対話です。計画を提示し、すべてを対象にするか一部にするかを尋ね（--select から選択解除したパッケージの依存先を除外する処理も含みます。計画内の updates エッジをたどってください。CLI は選択された項目だけを実行し、それ以外では実行途中でエラーになります）、実行を進め、結果を報告します。AppConfig JSON を手動で編集しないでください。更新順序を自分で計算しないでください。推移的な閉包について文章で推論しないでください。dxs に任せてください。jq で appConfig を操作しようとしたら、そこで中断してください。その作業は dxs source reference set の担当です。

ワークフロー

Phase 0  Establish origin+org  — user names the package; resolve its uniqueIdentifier (dxs marketplace
         search "<name>" --type componentmodule, or marketplace list --type componentmodule to browse) and
         pass the RESOLVED uid to -p, never the display name the user typed (see safety gates); take the
         newest published version from the user; pick the target org (auto only when the user sees exactly
         one AND didn't name a different one — if they name an org you're not logged into, confirm + switch
         identity via dxs auth login, see references); CONFIRM (a wrong version poisons every pin, a wrong
         org syncs the wrong tenant).
Phase 1  Plan                  — dxs -O json source cascade plan -p <uid> -v <version> --org <orgId>
Phase 2  Present & select      — render the tree; ask ALL / subset / review-only (see
         references/interaction-patterns.md); a cycle or conflict = hard stop.
Phase 3  Execute bottom-up     — dxs source cascade run --plan plan.json [--select …];
         narrate each republish (n of N).
Phase 4  Report                — republished packages (+ new versions) and stale applications
         to update separately.

各フェーズで使用する正確なコマンドについては、references/cascade-workflow.md に従ってください。

関連スキル

• datex-studio-shared — ブランチと接続の設定（上記の「必須の事前知識」を参照）。
• release-notes-generator — フェーズ 3 で --release-notes "<notes>" に渡すテキストを作成します。実行内で再公開されるすべてのノードにそのまま適用され、ノードごとには適用されない点に注意してください。
• commit-message-generator — cascade run は固定のコミットメッセージ（chore(deps): cascade update <uid>）を必ず書き込み、--commit-message フラグもありません。そのため、この関連スキルが適用されるのは、cascade run を使わずにノードごとのプリミティブ（branch commit）を手動で実行し、独自のメッセージを指定する場合だけです。これは現時点での制限事項であり、通常の方法ではありません。この手動での方法では、branch commit の確認プロンプトを省略するために -f（dxs ≥ 0.4.19）を、プレビューするために --dry-run を指定する必要があります。references/cascade-workflow.md を参照してください。

安全ゲート

• 計画を立てる前に、元のパッケージとバージョン、対象組織を確認してください（フェーズ 0）。バージョンを間違えるとすべてのピンが不正になり、組織を間違えると別のテナントが同期されます。
• -p に指定するのは、表示名ではなく解決済みの uniqueIdentifier です。 uniqueIdentifier は名前からスペースとアンダースコアを取り除きます（表示名 pkg_cascade_mid → uid pkgcascademid）。また、cascade plan は完全一致で照合するため、ID 形式に見える表示名（例：pkg_cascade_leaf）でもパッケージに一致せず、何もすることがないように見える、空の計画が黙って返されます。marketplace search が返した正確な文字列を渡し、dxs source referenced-from <uid> --org <id> で確認してください。
• Cascade は単一テナントです — フェーズ 1 では --org <id> を渡すため、計画の対象となるのは対象組織のパッケージだけです。他のテナントの利用者は除外されます（公開は所有組織に限定されているため、再公開もできません）。
• 対象組織が、現在ログインしている組織とは限りません。 organization list に表示されるのは、アクティブな ID のテナントだけです。また、cascade plan はテナントをまたいで読み取り専用で処理するため、公開権限のない組織に対しても計画が成功する場合があります。失敗が発生するのは run のときだけです（mainApplicationId に対する 404）。ユーザーが指定した組織が一覧に表示されない場合、表示されている組織に黙って切り替えたり、計画を立ててから失敗させたりしないでください。対象を確認し、切り替えの許可を得てから、そのテナントに dxs auth login --tenant-id <tenantId> でログインしてください。 dxs ≥ 0.5.0 では、そのテナントの ID がすでにキャッシュされていればログインはすぐに戻り、それ以外の場合はユーザーが完了するブラウザーが開きます。ヘッドレス環境の場合、または --use-device-code／--no-browser を指定した場合にのみ、デバイスコードが出力されます。references/cascade-workflow.md のフェーズ 0、手順 3a、および references/interaction-patterns.md →「ログインしていない対象組織」を参照してください。
• ブランチ／リポジトリ ID を推測しないでください — 計画には各ノードの Main ブランチ ID が含まれています。それを提示し、推測しないでください。
• 循環またはバージョンの競合があれば、必ず停止してください。 cascade plan は cycleDetected を設定し、reference set は競合があると中止します。報告し、強行しないでください。
• 計画を提示した後、続行するかどうかを明示的に確認してください — ユーザーが選択するまで、何も変更されません（フェーズ 2）。
• アプリケーションは自動公開されません — staleApplications にのみ表示されます。
• 失敗を調査できる状態にしてください — ノードで失敗した場合、そのフィーチャーブランチを保持して報告し、残りのノードを --select で指定して再開する方法を提示してください。
• 公開権限 — ユーザーにパッケージの公開権限がない場合、最初の公開は失敗します。早めに伝えてください。