create-webroles

プラグインの確認：node "${PLUGIN_ROOT}/scripts/check-version.js" を実行します。メッセージが出力された場合は、続行する前にユーザーに表示してください。

Web ロールの作成

Power Pages SPA サイト用の Web ロールを作成します。Web ロールは、さまざまな種類のサイトユーザーに対する権限とアクセスレベルを定義します。

非 SPA サイトでも同じロールスキーマと一意性制約を使用しますが、メタデータのルートは <projectRoot>/.powerpages-site または直接開いた PAC エクスポートのいずれかになります。

サイトタイプの振り分け

以下のワークフローを読み取ったり実行したりする前に、まず既存の SPA プロジェクト検索を行います。

• 既存のファイル検索パターンを使用して、現在のディレクトリまたは直下のサブディレクトリから powerpages.config.json を探します。

• 見つかった場合は、以下の既存の SPA ワークフローを続行します。フェーズ、プロンプト、ゲート、ファイル名、呼び出し元抑制の契約、デプロイの動作は変更しないでください。

• 既存の SPA 検索で powerpages.config.json が見つからなかった場合に限り、次を実行します。

  node "${PLUGIN_ROOT}/scripts/lib/detect-project-context.js"
  

• siteType: "non-spa" が返された場合は、${PLUGIN_ROOT}/skills/create-webroles/references/non-spa-site-workflow.md を読み、その手順に従います。以下の SPA ワークフローは実行しないでください。

• それ以外の場合はフェーズ 1 に進み、既存の未検出時の処理を維持します。

---

基本原則

• TaskCreate/TaskUpdate を使用する：すべてのフェーズを通じて進捗を追跡します。作業を始める前に、すべてのフェーズを含む ToDo リストを作成してください。
• 必ず UUID スクリプトを使用する：UUID を手動で生成しないでください。各 Web ロールに有効な UUID v4 値を生成するには、必ず ${PLUGIN_ROOT}/scripts/generate-uuid.js を使用してください。
• 一意性制約を維持する：anonymoususersrole: true にできるロールは 1 つだけで、authenticatedusersrole: true にできるロールも 1 つだけです。これらのフラグを設定する前に、必ず既存のロールを確認してください。
• 呼び出し元抑制モードはオプトインです：別のスキル（例：/add-ai-webapi）から $ARGUMENTS に [CALLED-BY-PARENT-SKILL] センチネルが含まれた状態で呼び出された場合、このスキルのデプロイに関するプロンプト（フェーズ 1 のデプロイ未実施時の確認、フェーズ 6 のデプロイ確認（手順 3）、終了時のリマインダー）を抑制し、ロールが作成されたらすぐに戻ります。呼び出し元がオーケストレーションの最後にまとめてデプロイします。人間による呼び出しでは、このモードは有効になりません。解析方法については、以下のフェーズ 0 を参照してください。

前提条件： Web ロール定義を格納する .powerpages-site フォルダー構造はデプロイ時に作成されるため、Web ロールを作成する前に、サイトを少なくとも 1 回デプロイしておく必要があります。

初期リクエスト： $ARGUMENTS

フェーズ 0：呼び出し元抑制モードの検出

$ARGUMENTS を確認します。テキストにセンチネル [CALLED-BY-PARENT-SKILL] が含まれている場合、内部フラグ caller-suppress = true を設定し、後続のフェーズで参照します。診断用に、任意のトークン caller=<skill-name> がセンチネルの後に続く場合があります（例：caller=add-ai-webapi）。最終的な概要に記録しますが、これを条件分岐には使用しないでください。

フラグが設定されている場合、このスキルが通常提示するすべてのデプロイに関するプロンプトをスキップします。

• フェーズ 1 のデプロイ未実施時の確認：.powerpages-site が存在しない場合、今すぐデプロイするようユーザーに確認してはいけません。明確な契約違反メッセージを呼び出し元に返して停止します。呼び出し元は、実行前にこの条件を確認しておく必要があります。
• **フェーズ 6 のデプロイ確認（手順 3）**と終了時の「/deploy-site を実行してください」というリマインダー：どちらもスキップします。呼び出し元がオーケストレーションの最後に、デプロイするかどうかをまとめて判断します。

センチネルがない場合は、これまでどおり全対話型フローを実行します。これは回帰を防ぐための措置であり、人間による呼び出し時の動作は変更されません。

---

ワークフロー

1. フェーズ 1：サイト構造を確認する → .powerpages-site/web-roles/ ディレクトリを確認します
2. フェーズ 2：既存のロールを確認する → 現在の Web ロール YAML ファイルを読み取ります
3. フェーズ 3：新しいロールを決定する → サイトを分析し、必要なロールをユーザーに確認します
4. フェーズ 4：Web ロールファイルを作成する → Node スクリプトで UUID を生成して YAML ファイルを作成します
5. フェーズ 5：Web ロールを検証する → 作成したすべてのファイルが存在すること、有効な UUID を持つこと、フラグが正しいことを検証します
6. フェーズ 6：レビューしてデプロイする → 概要を提示して、デプロイに進みます

---

フェーズ 1：サイト構造を確認する

目標：.powerpages-site/web-roles/ ディレクトリが存在し、Web ロールファイルを配置できる状態であることを確認します

アクション：

1. プロジェクトルート（**/powerpages.config.json）を見つけ、.powerpages-site/web-roles/ があるか確認します。

🚦 ゲート（plan · create-webroles:1.deploy-first）： .powerpages-site がありません。このフォルダーがないため、スキルを続行できません。まずデプロイするか、停止するかを確認してください。

トリガー： フェーズ 1 で .powerpages-site ディレクトリが見つかりませんでした。 確認する理由： 存在しないパスに書き込まれた Web ロール YAML ファイルは、デプロイ時に読み込まれません。ユーザーはロールが作成されたと思っても、実際には作成されていないためです。 キャンセルした場合： 何もありません。YAML ファイルは書き込まれていません。

2. .powerpages-site が存在しない場合：

   • 呼び出し元抑制モード（フェーズ 0 のフラグ）の場合：契約違反のメッセージを表示して停止します。このスキルを呼び出す前に、呼び出し元のスキルがこのフォルダーの存在を確認している必要があります。
   • それ以外の場合：AskUserQuestion を使って、まずデプロイするようユーザーに確認します（選択肢：「はい、今すぐデプロイする（推奨）」「いいえ、後で実行します」）。「はい」の場合は /deploy-site を呼び出してから、フェーズ 2 を再開します。「いいえ」の場合は停止します。

3. .powerpages-site は存在するが web-roles/ が存在しない場合： <PROJECT_ROOT>/.powerpages-site/web-roles/ ディレクトリを作成します。

4. 両方とも存在する場合： フェーズ 2 に進みます。

出力：.powerpages-site/web-roles/ ディレクトリが存在し、準備ができていることを確認します

---

フェーズ 2：既存のロールを確認する

目標：サイトにすでに定義されているすべての Web ロールを特定します

アクション：

1. .powerpages-site/web-roles/ ディレクトリ内のすべての YAML ファイルを読み取ります。各ファイルは、次の形式で 1 つの Web ロールを表します。

   anonymoususersrole: false
   authenticatedusersrole: false
   id: 778fa3d0-a2ef-4d2b-98b8-e6c7d8ce1444
   name: Administrators
   

2. 各ファイルを解析し、既存の Web ロール（名前、ID、フラグ）の一覧を作成します。

3. 既存のロールをユーザーに提示します。

   「サイトで次の既存の Web ロールが見つかりました。」

   • Administrators（ID：778fa3d0-...、認証済み：false、匿名：false）
   • (など)

4. ロールがまだ存在しない場合は、ユーザーに伝えます。

   「サイトには現在、Web ロールが定義されていません。」

出力：既存の Web ロールの名前、ID、フラグを含む完全な一覧

---

フェーズ 3：新しいロールを決定する

目標：サイトのニーズとユーザーの入力に基づいて、作成する新しい Web ロールを決定します

アクション：

🚦 ゲート（plan · create-webroles:3.role-selection）： 提案された Web ロールとカスタム Web ロールを複数選択します。フェーズ 4 の YAML ファイル書き込みに反映されます。

トリガー： フェーズ 2 で既存のロールを調査し、フェーズ 3 で新しいロールを提案します。 確認する理由： 誤ったロールがローカルに作成されると修正できますが、.powerpages-site/web-roles/ フォルダーに不要な変更が増えます。 キャンセル時の状態： 変更なし — YAML ファイルはまだ書き込まれていません。

1. サイトの目的と既存のロールに基づいて、適切な Web ロールを提案します。AskUserQuestion を使用してユーザーに確認します。

   Power Pages サイトでよく使われる Web ロールには、次のものがあります。

   • Administrators — サイト管理へのフルアクセス
   • Authenticated Users — ログイン済みユーザーのデフォルトロール（authenticatedusersrole: true を設定）
   • Anonymous Users — 未ログインの訪問者のデフォルトロール（anonymoususersrole: true を設定）
   • Content Editors — サイトコンテンツを編集できるユーザー
   • Moderators — コミュニティコンテンツをモデレートできるユーザー
   • ビジネスニーズに基づくカスタムロール

2. 作成するロールをユーザーに尋ねます。

   質問	選択肢
   サイト用にどの Web ロールを作成しますか？提案から選択することも、カスタムロールを指定することもできます。	(サイトのコンテキスト、既存のロール、ビジネスドメインに基づいて、関連する提案を提示します)

   重要：すでに存在するロールは提案しないでください。選択肢を提示する前に、既存のロール名を除外します。

3. ユーザーがカスタムロール名も指定できるようにします。

出力：作成する新しい Web ロールの確認済みリスト

---

フェーズ 4：Web ロールファイルを作成する

目標：新しい Web ロールごとに、有効な UUID を含む適切な形式の YAML ファイルを生成します

アクション：

ユーザーが承認した新しい Web ロールごとに、.powerpages-site/web-roles/ に YAML ファイルを作成します。

4.1 UUID を生成する

各ロールについて、Node スクリプトを使用して UUID を生成します。自分で UUID を生成することは絶対に避け、必ずスクリプトを使用してください。

node "${PLUGIN_ROOT}/scripts/generate-uuid.js"

4.2 YAML ファイルを作成する

ファイル名には、ロール名をケバブケースにしたものに .yml 拡張子を付けます（例：Administrators → administrators.yml、Content Editors → content-editors.yml）。

次の正確な形式でファイルを書き込みます（4 つのフィールド、余分な空白やコメントなし）。

anonymoususersrole: <true if this is the anonymous users role, false otherwise>
authenticatedusersrole: <true if this is the authenticated users role, false otherwise>
id: <UUID from generate-uuid.js>
name: <Role Name>

ルール：

• anonymoususersrole: true にできるロールは 1 つだけです
• authenticatedusersrole: true にできるロールは 1 つだけです
• 既存のロールですでにこれらのフラグのいずれかが true に設定されている場合、新しいロールには再設定しないでください
• 各ロールには、スクリプトで生成した一意の UUID が必要です。ロールごとにスクリプトを 1 回実行してください

出力：新しい Web ロールの YAML ファイルをすべて作成済み

---

フェーズ 5：Web ロールを検証する

目標：作成した Web ロールファイルがすべて存在し、形式が正しく、制約を満たしていることを検証します

アクション：

1. .powerpages-site/web-roles/ 内のすべてのファイルを一覧表示し、新しいファイルをそれぞれ読み込んで正しく書き込まれていることを確認します。

2. 新しい Web ロールファイルごとに、次の点を確認します。

   • ファイルが想定されたパスに存在すること
   • id フィールドが有効な UUID v4 形式であること
   • name フィールドが想定されるロール名と一致すること
   • anonymoususersrole と authenticatedusersrole が有効なブール値であること

3. すべてのロールファイル（既存のものと新しいもの）の間で、一意性の制約を確認します。

   • anonymoususersrole: true を持つロールが 1 つ以下であること
   • authenticatedusersrole: true を持つロールが 1 つ以下であること
   • ロール間に重複した id 値がないこと

4. いずれかのファイルが検証に失敗した場合は、先に進む前に問題を修正します。

出力：すべての Web ロールファイルを検証済み — 正しい形式、有効な UUID、制約違反なし

---

フェーズ 6：確認とデプロイ

目標：作成したロールの概要を提示し、デプロイするかどうかを確認します

アクション：

1. スキルの使用状況を記録します：

   参照先：${PLUGIN_ROOT}/references/skill-tracking-reference.md

   参照先に記載されているスキル使用状況の記録手順に従って、このスキルの使用状況を記録します。--skillName "CreateWebroles" を使用してください。

2. 作成した内容の概要を提示します：

   「次の新しい Web ロールを作成しました。」

ロール名	ID	匿名	認証済み
コンテンツ編集者	a1b2c3d4-...	false	false
(その他)

🚦 ゲート（plan · create-webroles:6.deploy）： 作成後の最終確認 — 新しいロールを有効にするため、今すぐデプロイするか、後で行うかを確認します。

トリガー： フェーズ 5 の検証が成功しました。 確認する理由： /deploy-site を自動で呼び出すと、PAC CLI が指している環境にサイトがプッシュされます。誤った環境へのプッシュは取り消しが困難です。 キャンセルした場合： 何も起こりません。YAML ファイルはディスク上に残り、デプロイは実行されません。

3. 呼び出し元による抑制モード（フェーズ 0 のフラグ）の場合は、デプロイの確認と終了時のリマインダーを 完全に省略します。作成したロールの概要を呼び出し元に返し、終了します。デプロイするかどうかは、 呼び出し元がオーケストレーション全体の最後に一度だけ判断します。委譲先にデプロイのリマインダーを 入れると、親スキルの実行ごとにユーザーに 2～3 回重複して確認することになります。

   それ以外の場合は、新しいロールを適用するためにサイトをデプロイするかどうか、ユーザーに確認します：

   質問	選択肢
   新しい Web ロールはローカルに作成されました。Power Pages に適用するには、サイトをデプロイする必要があります。今すぐデプロイしますか？	はい。今すぐデプロイする（推奨）、いいえ。後でデプロイする

4. 「はい。今すぐデプロイする」の場合：デプロイスキルを実行するようユーザーに伝えます：

   「/deploy-site を実行してサイトをデプロイし、新しい Web ロールを適用してください。」

5. 「いいえ。後でデプロイする」の場合：了承し、リマインダーを伝えます：

   「問題ありません。Power Pages 環境に新しい Web ロールを適用する準備ができたら、/deploy-site を使用してサイトをデプロイしてください。」

出力：概要を提示し、デプロイするかどうかを確認します

---

重要な注意事項

主な判断ポイント（ユーザーの応答を待つ）

1. フェーズ 1 の後：.powerpages-site が存在しない場合は、デプロイするかどうかを確認します
2. フェーズ 3 の後：作成するロールを確認します
3. フェーズ 6 の後：デプロイするか、スキップするかを確認します

進行状況の追跡

フェーズ 1 を開始する前に、TaskCreate を使用して全フェーズを含むタスクリストを作成します：

タスクの件名	activeForm	説明
サイト構成を確認する	サイト構成を確認中	.powerpages-site/web-roles/ ディレクトリを確認し、必要に応じて作成する
既存のロールを確認する	既存のロールを確認中	現在の Web ロールの YAML ファイルを読み込み、既存のロール一覧を作成する
新しいロールを決定する	新しいロールを決定中	サイトのニーズを分析し、作成するロールをユーザーに確認する
Web ロールのファイルを作成する	Web ロールのファイルを作成中	新しいロールごとに、Node スクリプトから UUID を取得して YAML ファイルを生成する
Web ロールを検証する	Web ロールを検証中	すべてのファイルが存在し、有効な UUID が設定され、一意性の制約を満たしていることを検証する
確認してデプロイする	確認してデプロイ中	作成したロールの概要を提示し、デプロイするかどうかを確認する

各タスクの開始時に TaskUpdate で in_progress に、完了時に completed に設定します。これにより、ユーザーが進行状況を確認でき、ワークフローを確実に進められます。

---

フェーズ 1：サイト構成の確認から開始してください