@salesforce/templates 66.1.1 → 66.2.0

package/lib/templates/project/react-b2x/.a4drules/graphql/tools/knowledge/lds-explore-graphql-schema.md

@@ -0,0 +1,227 @@
+# GraphQL Schema Reference
+
+This document provides guidance for AI agents working with the Salesforce GraphQL API schema in this project.
+
+## Schema File Location
+
+**The complete GraphQL schema is located at: `@schema.graphql`** (in the project root)
+
+> ⚠️ **Important**: The schema file is very large (~265,000+ lines). Do NOT read it entirely. Instead, use targeted searches to find specific types, fields, or operations.
+
+If the file is not present, generate it by running:
+```bash
+npm run graphql:get-schema
+```
+
+## Required Pre-Flight Check
+
+**BEFORE generating any GraphQL query, you MUST:**
+
+1. **Check if schema exists**: Look for `schema.graphql` in the project root
+2. **If schema is missing**: 
+   - Run `npm run graphql:get-schema` to download it
+   - Wait for the command to complete successfully
+   - Then proceed with schema exploration
+3. **If schema exists**: Proceed with targeted searches as described below
+
+> ⚠️ **DO NOT** generate GraphQL queries without first having access to the schema. Standard field assumptions may not match the target org's configuration.
+
+## Schema Structure Overview
+
+The schema follows the Salesforce GraphQL Wire Adapter pattern with these main entry points:
+
+### Query Entry Point
+```graphql
+type Query {
+  uiapi: UIAPI!
+}
+```
+
+### UIAPI Structure
+```graphql
+type UIAPI {
+  query: RecordQuery!           # For querying records
+  aggregate: RecordQueryAggregate!  # For aggregate queries
+  objectInfos: [ObjectInfo]     # For metadata
+  relatedListByName: RelatedListInfo
+}
+```
+
+### Mutation Entry Point
+```graphql
+type Mutation {
+  uiapi(input: UIAPIMutationsInput): UIAPIMutations!
+}
+```
+
+## How to Explore the Schema
+
+When you need to build a GraphQL query, use these search patterns:
+
+### 1. Find Available Fields for a Record Type
+Search for `type <ObjectName> implements Record` to find all queryable fields:
+```bash
+# Example: Find Account fields
+grep "^type Account implements Record" schema.graphql -A 50
+```
+
+### 2. Find Filter Options for a Record Type
+Search for `input <ObjectName>_Filter` to find filterable fields and operators:
+```bash
+# Example: Find Account filter options
+grep "^input Account_Filter" schema.graphql -A 30
+```
+
+### 3. Find OrderBy Options
+Search for `input <ObjectName>_OrderBy` for sorting options:
+```bash
+# Example: Find Account ordering options
+grep "^input Account_OrderBy" schema.graphql -A 20
+```
+
+### 4. Find Mutation Operations
+Search for operations in `UIAPIMutations`:
+```bash
+# Example: Find Account mutations
+grep "Account.*Create\|Account.*Update\|Account.*Delete" schema.graphql
+```
+
+### 5. Find Input Types for Mutations
+Search for `input <ObjectName>CreateInput` or `input <ObjectName>UpdateInput`:
+```bash
+# Example: Find Account create input
+grep "^input AccountCreateInput" schema.graphql -A 30
+```
+
+## Common Operator Types
+
+### StringOperators (for text fields)
+```graphql
+input StringOperators {
+  eq: String      # equals
+  ne: String      # not equals
+  like: String    # pattern matching (use % as wildcard)
+  lt: String      # less than
+  gt: String      # greater than
+  lte: String     # less than or equal
+  gte: String     # greater than or equal
+  in: [String]    # in list
+  nin: [String]   # not in list
+}
+```
+
+### OrderByClause
+```graphql
+input OrderByClause {
+  order: ResultOrder   # ASC or DESC
+  nulls: NullOrder     # FIRST or LAST
+}
+```
+
+## Query Pattern Examples
+
+### Basic Query Structure
+All record queries follow this pattern:
+```graphql
+query {
+  uiapi {
+    query {
+      <ObjectName>(
+        first: Int           # pagination limit
+        after: String        # pagination cursor
+        where: <Object>_Filter
+        orderBy: <Object>_OrderBy
+      ) {
+        edges {
+          node {
+            Id
+            <Field> { value }
+            # ... more fields
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+### Example: Query Accounts with Filter
+```graphql
+query GetHighRevenueAccounts($minRevenue: Currency) {
+  uiapi {
+    query {
+      Account(
+        where: { AnnualRevenue: { gt: $minRevenue } }
+        orderBy: { AnnualRevenue: { order: DESC } }
+        first: 50
+      ) {
+        edges {
+          node {
+            Id
+            Name { value }
+            AnnualRevenue { value }
+            Industry { value }
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+### Mutation Pattern
+```graphql
+mutation CreateAccount($input: AccountCreateInput!) {
+  uiapi(input: { AccountCreate: { input: $input } }) {
+    AccountCreate {
+      Record {
+        Id
+        Name { value }
+      }
+    }
+  }
+}
+```
+
+## Field Value Wrappers
+
+Salesforce GraphQL returns field values wrapped in typed objects:
+
+| Wrapper Type | Access Pattern |
+|-------------|----------------|
+| `StringValue` | `FieldName { value }` |
+| `IntValue` | `FieldName { value }` |
+| `BooleanValue` | `FieldName { value }` |
+| `DateTimeValue` | `FieldName { value displayValue }` |
+| `PicklistValue` | `FieldName { value displayValue }` |
+| `CurrencyValue` | `FieldName { value displayValue }` |
+
+## Agent Workflow for Building Queries
+
+**Pre-requisites (MANDATORY):**
+- [ ] Verified `schema.graphql` exists in project root
+- [ ] If missing, ran `npm run graphql:get-schema` and waited for completion
+- [ ] Confirmed connection to correct Salesforce org (if downloading fresh schema)
+
+**Workflow Steps:**
+
+1. **Identify the target object** (e.g., Account, Contact, Opportunity)
+2. **Search the schema** for the object type to discover available fields
+3. **Search for filter input** (`<Object>_Filter`) to understand filtering options
+4. **Search for orderBy input** (`<Object>_OrderBy`) for sorting capabilities
+5. **Build the query** following the patterns above
+6. **Validate field names** match exactly as defined in the schema (case-sensitive)
+
+## Tips for Agents
+
+- **Always verify field names** by searching the schema before generating queries
+- **Use grep/search** to explore the schema efficiently—never read the entire file
+- **Check relationships** by looking for `parentRelationship` and `childRelationship` comments in type definitions
+- **Look for Connection types** (e.g., `AccountConnection`) to understand pagination structure
+- **Custom objects** end with `__c` (e.g., `CustomObject__c`)
+- **Custom fields** also end with `__c` (e.g., `Custom_Field__c`)
+
+## Related Documentation
+
+- For generating mutations and queries, see `lds-generate-graphql-mutationquery.md`
+- For GraphQL best practices, see `lds-guide-graphql.md`

package/lib/templates/project/react-b2x/.a4drules/graphql/tools/knowledge/lds-generate-graphql-mutationquery.md

@@ -0,0 +1,212 @@
+# GraphQL Mutation Query Generation
+
+**Triggering conditions**
+1. Only if the `LDS_Guide_GraphQL` rule completed successfully
+2. Only if the query to generate is a mutation query
+
+## Your Role
+
+You are a GraphQL expert and your role is to help generate Salesforce compatible GraphQL mutation queries once the exploration phase has completed.
+
+You will leverage the context provided by the requesting user as well as the validation phase provided by the `LDS_Guide_GraphQL` rule. This tool will also provide you with a method to dynamically query the target org instance that you will use to test the generated query.
+
+If the `LDS_Guide_GraphQL` rule has not been executed yet, you **MUST** run it first, and then get back to mutation query generation.
+
+## Mutation Queries General Information
+
+**IMPORTANT**:
+1. **Mutation Types**: The GraphQL engine supports `Create`, `Update` and `Delete` operations
+2. **Id Based Mutations**: `Update` and `Delete` operations operate on Id-based entity identification
+3. **Mutation Schema**: Defined in the [mutation query schema](#mutation-query-schema) section
+
+## Mutation Query Generation Workflow
+
+Strictly follow the rules below when generating the GraphQL mutation query:
+1. **Input Fields Validation** - Validate that the set of fields validate [input field constraints](#mutation-queries-input-field-constraints)
+2. **Output Fields Validation** - Validate that the set of fields used in the select part of the query validate the [output fields constraints](#mutation-queries-output-field-constraints)
+3. **Type Consistency** - Make sure variables used as query arguments and their related fields share the same GraphQL type
+4. **Report Phase** - Use the [Mutation Query Report Template](#mutation-query-report-template) below to report on the previous validation phases
+5. **Input Arguments** - `input` is the default name for the argument, unless otherwise specified
+6. **Output Field** - For `Create` and `Update` operations, the output field is always named `Record`, and is of type EntityName
+7. **Query Generation** - Use the [mutation query](#mutation-query-templates) template and adjust it based on the selected operation
+8. **Output Format** - Use the [standalone](#mutation-standalone-default-output-format---clean-code-only)
+9. **Test the Query** - Use the [Generated Mutation Query Testing](#generated-mutation-query-testing) workflow to test the generated query
+    1. **Report First** - Always report first, using the proper output format, before testing
+
+## Mutation Query Schema
+
+**Important**: In the schema fragments below, replace **EntityName** occurrences by the real entity name (i.e. Account, Case...).
+**Important**: `Delete` operations all share the same generic `Record` entity name for both input and payload, only exposing the standard `Id` field.
+
+```graphql
+input EntityNameCreateRepresentation {
+  # Subset of EntityName fields here
+}
+input EntityNameCreateInput { EntityName: EntityNameCreateRepresentation! }
+type EntityNameCreatePayload { Record: EntityName! }
+
+input EntityNameUpdateRepresentation {
+  # Subset of EntityName fields here
+}
+input EntityNameUpdateInput { Id: IdOrRef! EntityName: EntityNameUpdateRepresentation! }
+type EntityNameUpdatePayload { Record: EntityName! }
+
+input RecordDeleteInput { Id: IdOrRef! }
+type RecordDeletePayload { Id: ID }
+
+type UIAPIMutations {
+  EntityNameCreate(input: EntityNameCreateInput!): EntityNameCreatePayload
+  EntityNameDelete(input: RecordDeleteInput!): RecordDeletePayload
+  EntityNameUpdate(input: EntityNameUpdateInput!): EntityNameUpdatePayload
+}
+```
+
+## Mutation Queries Input Field Constraints
+
+1. **`Create` Mutation Queries**:
+    1. **MUST** include all required fields
+    2. **MUST** only include createable fields
+    3. Child relationships can't be set and **MUST** be excluded
+    4. Fields with type `REFERENCE` can only be assigned IDs through their `ApiName` name
+2. **`Update` Mutation Queries**:
+    1. **MUST** include the id of the entity to update
+    2. **MUST** only include updateable fields
+    3. Child relationships can't be set and **MUST** be excluded
+    4. Fields with type `REFERENCE` can only be assigned IDs through their `ApiName` name
+3. **`Delete` Mutation Queries**:
+    1. **MUST** include the id of the entity to delete
+
+## Mutation Queries Output Field Constraints
+
+1. **`Create` and `Update` Mutation Queries**:
+    1. **MUST** exclude all child relationships
+    2. **MUST** exclude all `REFERENCE` fields, unless accessed through their `ApiName` member (no navigation to referenced entity)
+    3. Inaccessible fields will be reported as part of the `errors` attribute in the returned payload
+    4. Child relationships **CAN'T** be queried as part of a mutation
+    5. Fields with type `REFERENCE` can only be queried through their `ApiName` (no referenced entities navigation, no sub fields)
+2. **`Delete` Mutation Queries**:
+    1. **MUST** only include the `Id` field
+
+## Mutation Query Report Template
+
+Input arguments:
+- Required fields: FieldName1 (Type1), FieldName2 (Type2)...
+- Other fields: FieldName3 (Type3)...
+  Output fields: FieldNameA (TypeA), FieldNameB (TypeB)...
+
+## Mutation Query Templates
+
+```graphql
+mutation mutateEntityName(
+  # arguments
+) {
+  uiapi {
+    EntityNameOperation(input: {
+      # the following is for `Create` and `Update` operations only
+      EntityName: {
+        # Input fields
+      }
+      # the following is for `Update` and `Delete` operations only
+      Id: ... # id here
+    }) {
+      # the following is for `Create` and `Update` operations only
+      Record {
+        # Output fields
+      }
+      # the following is for `Delete` operations only
+      Id: ... # id here
+    }
+  }
+}
+```
+
+## Mutation Standalone (Default) Output Format - CLEAN CODE ONLY
+
+```javascript
+import { gql } from 'api/graphql.ts';
+const QUERY_NAME = gql`
+  mutation mutateEntity($input: EntityNameOperationInput!) {
+    uiapi {
+      EntityNameOperation(input: $input) {
+        # select output fields here depending on operation type
+      }
+    }
+  }
+`;
+
+const QUERY_VARIABLES = {
+  input: {
+    // The following is for `Create` and `Update` operations only
+    EntityName: {
+      // variables here
+    },
+    // The following is for `Update` and `Delete` operations only
+    Id: ... // id here
+  }
+};
+```
+
+**❌ DO NOT INCLUDE:**
+- Explanatory comments about the query
+- Field descriptions
+- Additional text about what the query does
+- Workflow step descriptions
+
+**✅ ONLY INCLUDE:**
+- Raw query string
+- Variables object
+- Nothing else
+
+## Generated Mutation Query Testing
+
+**Triggering conditions** - **ALL CONDITIONS MUST VALIDATE***
+1. Only if the [Mutation Query Generation Workflow](#mutation-query-generation-workflow) step global status is `SUCCESS` and you have a generated query
+2. Only if the query to generate is a mutation query
+3. Only if non manual method was used during `LDS_Guide_GraphQL` rule execution to retrieve introspection data
+
+**Workflow**
+1. **Report Step** - Explain that you are able to test the query using the same method used during introspection
+    1. You **MUST** report the method you will use, based on the one you used during `LDS_Guide_GraphQL` rule execution
+2. **Interactive Step** - Ask the user whether they want you to test the query using the proposed method
+    1. **WAIT** for the user's answer.
+3. **Input Arguments** - You **MUST** ask the user for the input arguments to use
+    1. **WAIT** for the user's answer.
+4. **Test Query** - If the user are OK with you testing the query:
+    1. Use the selected method to test the query
+    2. **IMPORTANT** - If you use the Salesforce CLI `sf api request graphql` command, you will need to inject the variable values directly into the query, as this command doesn't accept variables as a parameter
+5. **Result Analysis** - Retrieve the `data` and `errors` attributes from the returned payload, and report the result of the test as one of the following options:
+    1. `PARTIAL` if `data` is not an empty object, but `errors` is not an empty list - Explanation: some of the queried fields are not accessible on mutations
+    2. `FAILED` if `data` is an empty object - Explanation: the query is not valid
+    3. `SUCCESS` if `errors` is an empty list
+6. **Remediation Step** - If status is not `SUCCESS`, use the [`FAILED`](#failed-status-handling-workflow) or [`PARTIAL`](#partial-status-handling-workflow) status handling workflows
+
+### `FAILED` Status Handling Workflow
+
+The query is invalid:
+1. **Error Analysis** - Parse and categorize the specific error messages
+2. **Root Cause Identification** - Use error message to identify the root cause:
+    - **Execution** - Error contains `invalid cross reference id` or `entity is deleted`
+    - **Syntax** - Error contains `invalid syntax`
+    - **Validation** - Error contains `validation error`
+    - **Type** - Error contains `VariableTypeMismatch` or `UnknownType`
+    - **Navigation** - Error contains `is not currently available in mutation results`
+    - **API Version** - Query deals with updates, you're testing with Connect API and error contains `Cannot invoke JsonElement.isJsonObject()`
+3. **Targeted Resolution** - Depending on the root cause categorization
+    - **Execution** - You're trying to update or delete an unknown/no longer available entity: either create an entity first, if you have generated the related query, or ask for a valid entity id to use
+    - **Syntax** - Update the query using the error message information to fix the syntax errors
+    - **Validation** - This field's name is most probably invalid, ask user for clarification and **WAIT** for the user's answer
+    - **Type** - Use the error details and GraphQL schema to correct argument's type, and adjust variables accordingly
+    - **Navigation** - Use the [`PARTIAL` status handling workflow](#partial-status-handling-workflow) below
+    - **API Version** - `Record` selection is only available with API version 64 and higher, **report** the issue, and try again with API version 64
+4. **Test Again** - Resume the [query testing workflow](#generated-mutation-query-testing) with the updated query (increment and track attempt counter)
+5. **Escalation Path** - If targeted resolution fails after 2 attempts, ask for additional details and restart the entire GraphQL workflow, going again through the introspection phase
+
+### `PARTIAL` Status Handling Workflow
+
+The query can be improved:
+1. Report the fields mentioned in the `errors` list
+2. Explain that these fields can't be queried as part of a mutation query
+3. Explain that the query might be considered as failing, as it will report errors
+4. Offer to remove the offending fields
+5. **WAIT** for the user's answer
+6. If they are OK with removing the fields restart the [generation workflow](#mutation-query-generation-workflow) with the new field list

package/lib/templates/project/react-b2x/.a4drules/graphql/tools/knowledge/lds-generate-graphql-readquery.md

@@ -0,0 +1,185 @@
+# GraphQL Read Query Generation
+
+**Triggering conditions**
+1. Only if the `LDS_Guide_GraphQL` rule completed successfully
+2. Only if the query to generate is a read query
+
+## Your Role
+
+You are a GraphQL expert and your role is to help generate Salesforce compatible GraphQL read queries once the exploration phase has completed.
+
+You will leverage the context provided by the requesting user as well as the validation phase provided by the `LDS_Guide_GraphQL` rule.
+
+If the `LDS_Guide_GraphQL` rule has not been executed yet, you **MUST** run it first, and then get back to read query generation. This tool will also provide you with a method to dynamically query the target org instance that you will use to test the generated query.
+
+## Read Query Generation Workflow
+
+Strictly follow the rules below when generating the GraphQL read query:
+1. **No Proliferation** - Only generate for the explicitly requested fields, nothing else
+2. **Unique Query** - Leverage child relationships to query entities in one single query
+3. **Navigate Entities** - Always use `relationshipName` to access reference fields and child entities
+    1. **Exception** - if the `relationshipName` field is null, you can't navigate the related entity, and will have to return the `Id` itself
+4. **Leverage Fragments** - Generate one fragment per possible type on polymorphic fields (field with `dataType="REFERENCE"` and more than one entry in `referenceToInfos` introspection attribute)
+5. **Type Consistency** - Make sure variables used as query arguments and their related fields share the same GraphQL type
+6. **Type Enforcement** - Make sure to leverage field type information from introspection and GraphQL schema to generate field access
+7. **Semi and anti joins** - Use the semi-join or anti-join templates to filter an entity with conditions on child entities
+8. **Query Generation** - Use the [template](#read-query-template) to generate the query
+9. **Output Format** - Use the [standalone](#read-standalone-default-output-format---clean-code-only) 
+10. **Test the Query** - Use the [Generated Read Query Testing](#generated-read-query-testing) workflow to test the generated query
+    1. **Report First** - Always report first, using the proper output format, before testing
+
+## Read Query Template
+
+```graphql
+query QueryName {
+  uiapi {
+    query {
+      EntityName(
+        # conditions here
+      ) {
+        edges {
+          node {
+            # Direct fields
+            FieldName { value }
+
+            # Non-polymorphic reference (single type)
+            RelationshipName {
+              Id
+              Name { value }
+            }
+
+            # Polymorphic reference (multiple types)
+            PolymorphicRelationshipName {
+              ...TypeAInfo
+              ...TypeBInfo
+            }
+
+            # Child relationship (subquery)
+            RelationshipName(
+              # conditions here
+            ) {
+              edges {
+                node {
+                  # fields
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}
+
+fragment TypeAInfo on TypeA {
+  Id
+  SpecificFieldA { value }
+}
+
+fragment TypeBInfo on TypeB {
+  Id
+  SpecificFieldB { value }
+}
+```
+
+## Semi-Join and Anti-Join Condition Template
+
+Semi-joins (resp. anti-joins) condition leverage parent-child relationships and allow filtering the parent entity using a condition on child entities.
+This is a standard `where` condition, on the parent entity's `Id`, expressed using the `inq` (resp. `ninq`, i.e. not `inq`) operator. This operator accepts two attributes:
+- The child entity camelcase name to apply the condition on, with a value expressing the condition
+- The field name on the child entity containing the parent entity `Id`, which is the `fieldName` from the `childRelationships` information for the child entity
+- If the only condition is related child entity existence, you can use an `Id: { ne: null }` condition
+
+### Semi-Join Example - ParentEntity with at least one Matching ChildEntity
+
+```graphql
+query testSemiJoin {
+  uiapi {
+    query {
+      ParentEntity (
+        where: {
+          Id: {
+            inq: {
+              ChildEntity: {
+                # standard conditions here
+                Name: { like: "test%" }
+                Type: { eq: "some value" }
+              },
+              ApiName: "parentIdFieldInChild"
+            }
+          }
+        }
+      ) {
+        edges {
+          node {
+            Id
+            Name { value }
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+### Anti-Join Example - ParentEntity with no Matching ChildEntity
+
+Same example as the [Semi-Join Example](#semi-join-example---parententity-with-at-least-one-matching-childentity), but replacing the `inq` operator by the `ninq` one.
+
+## Read Standalone (Default) Output Format - CLEAN CODE ONLY
+
+```javascript
+const QUERY_NAME = `
+  query GetData {
+    // query here
+  }
+`;
+
+const QUERY_VARIABLES = {
+  // variables here
+};
+```
+
+**❌ DO NOT INCLUDE:**
+- Explanatory comments about the query
+- Field descriptions
+- Additional text about what the query does
+- Workflow step descriptions
+
+**✅ ONLY INCLUDE:**
+- Raw query string
+- Variables object
+- Nothing else
+
+## Generated Read Query Testing
+
+**Triggering conditions** - **ALL CONDITIONS MUST VALIDATE***
+1. Only if the [Read Query Generation Workflow](#read-query-generation-workflow) step global status is `SUCCESS` and you have a generated query
+2. Only if the query to generate is a read query
+3. Only if non manual method was used during `LDS_Guide_GraphQL` rule execution to retrieve introspection data
+
+**Workflow**
+1. **Report Step** - Explain that you are able to test the query using the same method used during introspection
+    1. You **MUST** report the method you will use, based on the one you used during `LDS_Guide_GraphQL` rule execution
+2. **Interactive Step** - Ask the user whether they want you to test the query using the proposed method
+    1. **WAIT** for the user's answer.
+3. **Test Query** - If the user are OK with you testing the query:
+    1. Use the selected method to test the query
+    2. Report the result of the test as `SUCCESS` if the query executed without error, or `FAILED` if you got errors
+    3. If the query executed without any errors, but you received no data, then the query is valid, and the result of the test is `SUCCESS`
+4. **Remediation Step** - If status is `FAILED`, use the [`FAILED` status handling workflows](#failed-status-handling-workflow)
+
+### `FAILED` Status Handling Workflow
+
+The query is invalid:
+1. **Error Analysis** - Parse and categorize the specific error messages
+2. **Root Cause Identification** - Use error message to identify the root cause:
+    - **Syntax** - Error contains `invalid syntax`
+    - **Validation** - Error contains `validation error`
+    - **Type** - Error contains `VariableTypeMismatch` or `UnknownType`
+3. **Targeted Resolution** - Depending on the root cause categorization
+    - **Syntax** - Update the query using the error message information to fix the syntax errors
+    - **Validation** - This field's name is most probably invalid, ask user for clarification and **WAIT** for the user's answer
+    - **Type** - Use the error details and GraphQL schema to correct argument's type, and adjust variables accordingly
+4. **Test Again** - Resume the [query testing workflow](#generated-read-query-testing) with the updated query (increment and track attempt counter)
+5. **Escalation Path** - If targeted resolution fails after 2 attempts, ask for additional details and restart the entire GraphQL workflow, going again through the introspection phase