experience-lds-graphql-generate

LDS GraphQL の構築

スタンドアロンのクエリとして、または lightning/graphql アダプターを介して Lightning Web Component に組み込む形で、スキーマ検証済みの Salesforce LDS GraphQL クエリ（読み取りまたはミューテーション）を生成します。このスキルは、スキーマを信頼できる唯一の情報源とするワークフローをエンドツーエンドで実現します。組織に応じた手順には、scripts/fetch-lds-graphql-schema.sh（スキーマのイントロスペクション用）と scripts/test-lds-graphql-query.sh（接続済み組織での検証用）の2つの bash スクリプトが付属しています。

使用する場合

• Salesforce GraphQL クエリ（標準オブジェクト、カスタムオブジェクト、または設定オブジェクト）の作成、変更、または統合を行う場合。
• GraphQL を介して LDS データを使用または変更する LWC を構築または更新する場合。
• クエリを作成する前に、組織のスキーマをイントロスペクションする場合。
• 生成したクエリを接続済みの組織に対してエンドツーエンドで検証する場合。

次の場合は、このスキルを使用しないでください。

• REST ベースの UI API（LDS ワイヤーアダプターを使用してください。experience-lds-best-practices-apply を参照）。
• Apex コールアウトまたはカスタム GraphQL エンドポイント — このスキルの対象は LDS に限られます。
• データ要件の特定 — これは experience-lds-data-requirements-generate の対象です。

前提条件

• 接続済みの Salesforce 組織（ユーザー名またはエイリアス）。スキーマを取得する前に、ユーザーの確認が必要です。決して推測しないでください。
• スキーマの取得に使用する Salesforce CLI / sf がシェルで利用可能であること。
• 以下を決定していること：
  • Namespace — uiapi（デフォルト：標準オブジェクトとカスタムオブジェクト）または setup（権限セット、プロファイルなどの設定オブジェクト）。
  • クエリの種類 — read（デフォルト）または mutation。
  • 出力形式 — standalone（GraphQL と変数をそのまま出力）または LWC integration（コンポーネントの配線を含む完全な出力）。

基本ルール

以下はすべての手順に適用される、このスキルが徹底するルールです。

1. 順次実行 — ステップ 1→6 は順番に実行します。実行条件を満たさない場合を除き、すべてのステップが必須です。
2. 失敗時は停止 — ステップが失敗した場合、問題が解決するまで後続のステップに進めません。
3. スキーマを唯一の信頼できる情報源とする — エンティティ名、フィールド名、フィールド型、リレーションシップはすべて、schema.graphql のイントロスペクション結果から取得してください。一般的な Salesforce の知識を使ってはいけません（例：Owner が User であると決めつけないでください。ポリモーフィック型の可能性があります）。
4. 各ステップを報告する — 次に進む前に、用意されたテンプレートを使用してください。
5. エラー報告 — エラーを分類し、生のツール出力をチャットにそのまま表示してはいけません。

ワークフロー

規範となるワークフロー全体は references/generation-guide.md にあります。開始前にお読みください。読み取りクエリの詳細は references/generation-query.md、ミューテーションの詳細は references/generation-mutation.md にあります。

ステップ 1 — クエリの基本情報

以下を収集し、ユーザーに復唱します。

Query type:       [read | mutation]
Namespace:        [uiapi | setup]
Output format:    [standalone | LWC integration]

不明な点があれば、一度だけ質問して返答を待ちます。

ステップ 2 — スキーマの取得

1. usernameOrAlias を尋ねます。コンテキストからデフォルトを推測できる場合は、それを提示し、明示的な確認を待ちます。
2. 確認済みのエイリアスを使用して scripts/fetch-lds-graphql-schema.sh USERNAME_OR_ALIAS [OUTPUT_PATH] [API_VERSION] を実行します。スクリプトは SDL を schema.graphql（または指定したパス）に書き込み、スキーマがチャットのコンテキストに入らないようにします。OUTPUT_PATH に空でない schema.graphql がすでに存在する場合、スクリプトは早期終了します（再取得するには LDS_FETCH_FORCE=1 を設定します）。
3. 失敗した場合：必ず停止し、エラーを分類して報告し、組織へのアクセスを解決するようユーザーに依頼してから再試行します。

スキーマファイルの使用方法

スキーマは 265,000 行を超えます。ファイル全体を読み込んではいけません — 対象を絞った grep 呼び出しのみを使用してください。

• オブジェクト型：^type <ObjectName> implements Record を -A 100 付きで検索します。
• フィルター：^input <ObjectName>_Filter を -A 50 付きで検索します。
• OrderBy：^input <ObjectName>_OrderBy を -A 30 付きで検索します。
• ミューテーション入力：^input <ObjectName>(Create|Update)Input を -A 50 付きで検索します。

検索予算：エンティティごとに grep 呼び出しは最大 4～5 回です。実行前に計画してください。

ステップ 3 — エンティティの特定

1. エンティティ名はPascalCaseです。
2. 名前が指定されていない場合は、^type <Name> implements Record に一致する候補を抽出します。
3. 未解決のエンティティが残っている場合は、ユーザーに質問して回答を待ちます。
4. 次の内容を報告します。

   Identified entities:
   - EntityName (Field1, Field2, ...)
   Unknown entities:
   - <textual name>
   Step 3 status: SUCCESS | FAILED
   

5. Unknown entities が空でない場合 → ステータスを FAILED に設定 → 詳細を確認するよう依頼 → ステップ 3 を再開します。

ステップ 4 — エンティティの反復的なイントロスペクション

反復の上限：3 サイクル（主要エンティティ → 参照先 → 子の関係）。3 サイクル後は必ず停止します。

サイクルごとに：

1. すでにイントロスペクション済みのエンティティをリストから削除します。
2. 上記のスキーマパターンを使って、残りのエンティティのフィールドを grep します。
3. 標準的なフィールド型を抽出します。
4. 参照フィールド（Owner: User）を特定します。エンティティによって同じ名前のフィールドでも型が異なる場合があるため、エンティティごとに確認します。フィールドの解決先が複数のエンティティ型になる場合は、ポリモーフィックとしてマークし、インラインフラグメント（... on TypeA、... on TypeB）を使う計画を立てます。
5. 子の関係（Contacts: ContactConnection などのConnection型）を特定します。新しいエンティティを未知のエンティティのリストに追加します。
6. 未知のエンティティがリストに残っていて、反復回数が 3 未満の場合は、ループします。
7. 次の内容を報告します。

   [PASS|FAIL] EntityName
     - Standard fields: FieldName (type), ...
     - Reference fields: FieldName → TargetType, ...
     - Polymorphic fields: FieldName → [TypeA, TypeB], ...
     - Child relationships: RelationshipName → ChildType, ...
     - Unknown fields: FieldName, ...
   Introspection cycles used: N/3
   Step 4 status: SUCCESS | FAILED
   

8. いずれかのエンティティが [FAIL] の場合 → 全体を FAILED に設定 → 修正対応 → サイクルの開始位置から再開します。

ステップ 5 — 読み取りクエリの生成（クエリ型が read の場合のみ）

イントロスペクションのデータ、エンティティリスト、フィールド型、出力形式、および usernameOrAlias を入力として、references/generation-query.md に従って読み取りクエリを作成します。

references/generation-query.md のルールを適用します。対象は次のとおりです。

• クエリのルート／名前空間の選択（uiapi.query と setup.query）。
• フィールド選択の方針（実際に必要なフィールドだけを要求します。すべてのフィールドが課金対象のスキャンです）。
• フィルター演算子（eq、ne、in、nin、gt、gte、lt、lte、like、contains）。
• OrderBy（フィールドごとの方向指定）。
• ページネーション（first、after、last、before、edges.node、pageInfo）。
• ポリモーフィックなインラインフラグメント。
• エイリアスと変数プレースホルダー。
• 単独実行とLWC出力（lightning/graphql のワイヤーアダプター、gql タグ付きテンプレート、命令的な更新用の refreshGraphQL）。

ツールがエラーを返した場合は、分類して、どのように進めるかユーザーに確認します。

ステップ 6 — ミューテーションクエリの生成（クエリ型が mutation の場合のみ）

references/generation-mutation.md に従ってミューテーションを作成します。対象は次のとおりです。

• create、update、delete 操作の形式。
• 入力型（input grep パターンで検出する <Entity>CreateInput、<Entity>UpdateInput）。
• 必須フィールドと任意フィールド（スキーマの ! アノテーションに基づきます）。
• Id のみを使った参照フィールドの更新。
• 戻り値の選択 — キャッシュの整合性を保つために、ミューテーション後に読み戻すデータ。
• エラー処理（record.errors[]）。
• LWC との統合：lightning/graphql の graphqlMutate を使った命令的なミューテーション。

ステップ 7 — クエリのテスト

確認済みの usernameOrAlias を使って scripts/test-lds-graphql-query.sh USERNAME_OR_ALIAS 'QUERY' '<VARIABLES_JSON>' を実行し、レスポンスの形状またはサンプルをユーザーに提示します。エラーは分類し、そのまま表示しません。

相互参照

• 同梱スクリプト：
  • scripts/fetch-lds-graphql-schema.sh — 組織の /services/data/vX/graphql エンドポイントに対するGraphQLイントロスペクションクエリを使ってスキーマを取得します（LDSには /graphql/sdl ルートが公開されていません）。クエリ作成前に、組織／セッションごとに一度呼び出します。
  • scripts/test-lds-graphql-query.sh — 生成したクエリを /services/data/vX/graphql に対して組織のデータを使って検証します。
• 関連スキル：
  • experience-lds-best-practices-apply — LDS の一般原則、キャッシュのセマンティクス、ワイヤーと命令的な方式の選択。
  • experience-lds-data-requirements-generate — このスキルがクエリの「方法」を決める前に、クエリ対象を決める事前作業。
  • experience-lwc-generate — 生成されたワイヤーアダプターを適切にホストします。

例

単独の読み取り — 最小構成

query Accounts($limit: Int = 10) {
  uiapi {
    query {
      Account(first: $limit) {
        edges {
          node {
            Id
            Name { value }
          }
        }
      }
    }
  }
}

LWC との統合 — ワイヤーを使った読み取り

import { LightningElement, wire } from 'lwc';
import { gql, graphql } from 'lightning/graphql';

export default class AccountList extends LightningElement {
    @wire(graphql, {
        query: gql`
            query Accounts($limit: Int = 10) {
                uiapi {
                    query {
                        Account(first: $limit) {
                            edges { node { Id Name { value } } }
                        }
                    }
                }
            }
        `,
        variables: '$variables'
    })
    accounts;

    variables = { limit: 10 };

    get records() {
        return this.accounts?.data?.uiapi?.query?.Account?.edges ?? [];
    }
}

検証

• Step 4 の前に Step 3 status: SUCCESS、Steps 5/6 の前に Step 4 status: SUCCESS であること。
• 生成されたクエリのすべてのフィールドがイントロスペクションレポートに含まれていること（存在しないフィールドを捏造していないこと）。
• ポリモーフィックフィールドではインラインフラグメントを使用し、非ポリモーフィックフィールドでは使用していないこと。
• ミューテーションでは、すべての必須入力フィールド（スキーマ内の !）が含まれていること。
• scripts/test-lds-graphql-query.sh がエラーなしで終了すること。エラーが発生した場合は、分類された修正方法が提示されていること。
• 出力形式が LWC integration の場合、コンポーネントが lightning/graphql からインポートし、gql タグ付きテンプレートを使用し、ゲッターを介してデータを公開していること（HTML 内で直接公開していないこと）。