@salesforce/mcp-provider-lwc-experts 0.6.2 → 0.6.4

package/knowledge/graphql/generation-guide.md

@@ -0,0 +1,212 @@
+# GraphQL Query Generation Guidelines
+
+You are a GraphQL expert, and your role is to help craft GraphQL queries that match Salesforce schema requirements and specificities.
+
+This is the main instructions source, and you will leverage the following MCP tools to complete your task:
+
+- The `{{ldsExploreGraphqlSchemaToolName}}` MCP Tool provides Salesforce's static GraphQL schema information
+- The `{{ldsCreateGraphqlReadQueryToolName}}` MCP Tool is specialized in GraphQL read query generation
+- The `{{ldsCreateGraphqlMutationQueryToolName}}` MCP Tool is specialized in GraphQL mutation query generation
+
+**CRITICAL ENFORCEMENT RULES:**
+
+- **Workflow Enforcement** - You **MUST** follow the workflow steps below, in order
+- **Workflow Steps are Mandatory** - All workflow steps are mandatory, none can be skipped
+- **Workflow Steps Chaining** - Steps need to be chained one after the other
+- **Hard Stop on Failed Step** - Any failed step blocks the workflow until remediation actions are completed
+- **Step Status Reporting** - Each step must report final status in a clear and concise way
+- **Common Knowledge** - You **MUST NOT** rely on common Salesforce knowledge related to entities, always ask for introspection data - if not available, **FAIL** the query generation (hard stop)
+- **Never guess** - You **MUST NOT** guess field type, always rely on introspection data (e.g. Owner doesn't mean User, the field might have a different type or be polymorphic)
+
+## STEP 1: General Query Information
+
+### Information Workflow
+
+1. Identify namespace: one of `uiapi` or `setup`, defaults to `uiapi`
+2. Identify query type: one of `read` or `mutation`, defaults to `read`
+3. Identify desired output, either standalone or LWC integration
+4. Use the [information report template](#information-report-template) below to report result
+
+### Information Report Template
+
+You want to build a GraphQL {type} query on entities hosted in the {namespace} namespace.
+LWC integration {is|isn't} requested.
+
+## STEP 2: Select Introspection Method
+
+**IMPORTANT** - This is an **interactive step**, you **MUST** wait for the user to answer your questions, and you **MUST** pause until they do:
+Ask the user how they want to retrieve the introspection information using the following list:
+
+1. **_Manually_** - User will execute the queries for you
+2. **_Connect API_** - You will execute introspection queries using the `graphql`Connect API endpoint
+3. **_Salesforce CLI_** - You will execute introspection queries using Salesforce CLI
+
+**WAIT** for the user's answer.
+
+If user picks option 2, Connect API:
+
+1. **_Local org details_** - Ask for server url, API version (e.g. 65) and a valid OAuth token, and store these in url, version and token variables
+2. **_Default API Version_** - If no API version is provided, use 66 as the default value
+3. **_Escaping_** - Make sure to escape the token to account for shell limitations (e.g. the `!` character might need to be escaped when using bash)
+   **WAIT** for the user's answer.
+
+**Report** - Mention the method you will use to retrieve introspection data, one of `Salesforce CLI`, `Connect API` or `user manual request`; if `Connect API`, mention server url `{url}/services/data/v{version}.0/graphql` and token
+
+## STEP 3: Entities Identification
+
+**CRITICAL** Your goal is to extract and list **entities** involved in the query to generate:
+
+- **Entity Names** must obey CamelCase convention
+- **Introspection** - If some entity names are not provided and can't be deduced from context, use the [Map Entity Names](#map-entity-names) workflow
+- **Resolution** - If some entity names are resolved by the previous introspection sub step, ask the user for their names
+- Do **NOT** try to resolve exact field names, as this will be completed as part of [STEP 4](#step-4-iterative-entities-introspection)
+- **Report** - Use the [Identification Report Template](#identification-report-template) to report final step status
+
+### Map Entity Names
+
+**List Accessible Entities** - Get a list of accessible entities using one of the following options, depending on the method selected by [STEP 2](#step-2-select-introspection-method):
+
+1. If `Salesforce CLI` was selected, use the `sf sobject list --sobject all` command
+2. If `Connect API` was selected, use `curl` to retrieve introspection data, using the `/services/data/v66.0/ui-api/object-info/` endpoint
+3. Otherwise, you **MUST** ask the user to retrieve the list of accessible entities for you, and wait for their answer
+
+**Report Status** - Use the [report template](#identification-report-template) to report status
+**HARD STOP** - Evaluate [hard stop rules](#identification-hard-stop-rules)
+
+### Identification Hard Stop Rules
+
+**Triggering conditions** - ALWAYS
+
+If the unknown entity list is not empty:
+
+- the global step status is `FAILED`
+- stop generation
+- go through [remediation actions](#identification-remediation-actions)
+
+### Identification Report Template
+
+**Triggering conditions** - ALWAYS
+
+List identified entities:
+
+- `Entity1` (`Field1.1`, `Field1.2`, ...)
+  List unknown entities:
+- entity textual name
+
+### Identification Remediation Actions
+
+**Triggering conditions** - Only if the global status for the step is `FAILED`
+
+**Interactive** - Ask the user for clarification on any unknown entities, and restart [STEP 3](#step-3-entities-identification)
+
+## STEP 4: Iterative Entities Introspection
+
+**CRITICAL** Your goal is to extract and list entity **fields** involved in the query to generate
+
+### Introspection Workflow
+
+**Triggering conditions** - ALWAYS
+
+Rules:
+
+1. Start with the list of entities from [STEP 3](#step-3-entities-identification)
+2. **NO ASSUMPTIONS** - You **_MUST_** rely only on introspection data for field name and type
+3. **NO COMMON KNOWLEDGE** - You **_MUST_** rely only on introspection data for field name and type
+4. You **MUST** follow the workflow below until all entities involved in the query to generate are properly described
+
+**CRITICAL** - **WORKFLOW** - using the list of unknown entities, **_strictly_** follow the following steps, in order:
+
+1. **Cleanup** - Remove from the list all entities for which you already retrieved introspection information
+2. **Introspection Phase** - Request introspection data for all unknown entities
+   1. If you're allowed to use Salesforce CLI, you can use the `sf api request graphql --body "query getData { ... }"` using the [Introspection GraphQL Query](#introspection-graphql-query) query template to replace the $query variable
+   2. If you have valid url, version and token variables, use `curl` to retrieve introspection data, using the [Introspection GraphQL Query](#introspection-graphql-query) query template and proper escaping to avoid shell issues with token characters
+   3. If you don't have valid url, version or token info, you **MUST** ask the user to run the query for you using the [Introspection GraphQL Query](#introspection-graphql-query) query template and **WAIT** for them to provide the required data
+   4. **HARD STOP** - If you didn't get any introspection data back, **STOP** here, and jump to point 8 below
+3. **Fields Identification** - Using introspection data, retrieve requested field types
+4. **Reference Fields** - Using introspection data, identify reference requested fields (`dataType="REFERENCE"`)
+   1. **IMPORTANT** - Two fields with the same name from two different entities might have different types
+   2. retrieve possible types using the `referenceToInfos` attribute
+   3. **Polymorphic Fields** - Reference fields with more than entry in the `referenceToInfos` attribute are polymorphic
+   4. add any unknown entity references to the list of entities to introspect
+5. **Child Relationships** - Using introspection data, identify all requested fields that are child relationships using the `childObjectApiName` attribute
+   1. add any unknown types to the list of types to discover
+6. **Secondary Introspection Phase** - If list of types to discover is not empty, resume the process from point 1 above
+7. **Field Type Information** - Retrieve GraphQL detailed type information for all non reference non child relationships requested fields using the `{{ldsExploreGraphqlSchemaToolName}}` MCP tool
+8. **Report** - Use the [Introspection Report Template](#introspection-report-template) to report on retrieved information
+9. **Evaluate** - Evaluate the [Introspection Hard Stop Rules](#introspection-hard-stop-rules)
+
+### Introspection Hard Stop Rules
+
+**Triggering conditions** - ALWAYS
+
+**Critical rule** - If the global status is `FAILED`, **STOP** generation here, and go through [introspection remediation actions](#introspection-remediation-actions)
+
+### Introspection Remediation Actions
+
+**Triggering conditions** - Only if the global status for the step is `FAILED`
+
+**Action** - Ask for clarification on any unknown fields, and resume the [Introspection Workflow](#introspection-workflow).
+
+### Introspection Report Template
+
+**Critical rule** An entity is ✅ only if it has no unknown fields, otherwise it is ❌
+**Critical rule** If any of the entities is not checked in the report, the global status is `FAILED`
+
+Introspection phase:
+{✅|❌} `Entity1`
+
+- Standard fields: `Field1` (`type`), `Field2` (`type`)...
+- Reference fields: `Field3` (`referenceToInfos` information from introspection)...
+- Child relationships: `Field4` (`childObjectApiName` from introspection)
+- Unknown fields: `Field5`...
+  {✅|❌} `Entity2`
+- ...
+  Introspection workflow status: {SUCCESS|FAILED}
+
+### Introspection GraphQL Query
+
+**CRITICAL RULES**
+
+- When using the request below, proceed with batches of 3 entities max in order to limit the payload size.
+- When introspecting for mutation create queries, add `required` and `createable` to the `fields` field.
+- When introspecting for mutation update queries, add `updateable` to the `fields` field.
+- When introspecting for mutation create or update queries, make sure you query for all fields (no pre-filtering).
+- You don't need introspection for mutation delete queries, as you only need the `Id` field.
+
+```graphql
+query getData {
+  uiapi {
+    objectInfos(apiNames: ["EntityName1", "EntityName2", ...]) {
+      ApiName
+      childRelationships { childObjectApiName, fieldName, relationshipName }
+      fields { ApiName, dataType, relationshipName, referenceToInfos { ApiName } }
+    }
+  }
+}
+```
+
+## STEP 5: Read Query Generation
+
+**Triggering conditions**
+
+1. Only if the [iterative entities introspection](#step-4-iterative-entities-introspection) step global status is `SUCCESS`
+2. Only if the query to generate is a read query
+
+Run the `{{ldsCreateGraphqlReadQueryToolName}}` MCP Tool.
+
+## STEP 6: Mutation Query Generation
+
+**Triggering conditions**
+
+1. Only if the [iterative entities introspection](#step-4-iterative-entities-introspection) step global status is `SUCCESS`
+2. Only if the query to generate is a mutation query
+
+Run the `{{ldsCreateGraphqlMutationQueryToolName}}` MCP Tool.
+
+## COMMON WORKFLOW VIOLATIONS TO AVOID
+
+- **Bypass Hard Stop Rules** - When a [workflow](#introspection-workflow) step fails to complete, you **MUST** stop here and wait for the remediation action to be completed - **NEVER** attempt to proceed with subsequent rules
+- **Guess Field Name or Type** - You **MUST NOT** try to guess field name or type based on assumptions, only leverage introspection and schema data
+- **Skip Introspection Phase** - **NEVER** bypass introspection phase - only use data from introspection, whether you auto executed the query or asked the user to run it for you
+- **Invalid Type Consistency** - Strong typing must be enforced at all times, and type information must come either from introspection or using the GraphQL schema
+- **Bypass Workflow** - You **MUST** follow strictly steps in the [introspection workflow](#introspection-workflow), **NEVER** try to bypass any step, or continue with subsequent steps if the current one exited with a failed status

package/knowledge/graphql/generation-mutation.md

@@ -0,0 +1,265 @@
+# GraphQL Mutation Query Generation
+
+**Triggering conditions**
+
+1. Only if the `{{ldsGuideGraphqlToolName}}` MCP Tool 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 `{{ldsGuideGraphqlToolName}}` MCP Tool. 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 `{{ldsGuideGraphqlToolName}}` MCP Tool 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) or [LWC](#mutation-lwc-integration-only-when-requested-output-format) output format templates based on desired output
+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
+
+If generating for LWC, the variable should provide the entire `input` argument:
+
+```javascript
+const QUERY_NAME = `
+  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
+
+## Mutation LWC Integration (Only When Requested) Output Format
+
+When integrating within an LWC:
+
+1. You must use the `executeMutation` imperative adapter
+2. The first parameter must be the result of calling the `gql` tag function on the query
+3. Both the `executeMutation` imperative adapter and the `gql` tag function must be imported from the `lightning/graphql` package
+
+```javascript
+import { LightningElement, wire } from 'lwc';
+import { gql, executeMutation } from 'lightning/graphql';
+
+export default class MyComponent extends LightningElement {
+  get mutationQuery() {
+    return gql`
+      mutation operationEntityName {
+        // mutation query here
+      }
+    `;
+  }
+
+  async mutateEntity() {
+    const result = await executeMutation({
+      query: mutationQuery,
+      variables: {
+        // variables here
+      },
+    });
+    // do something with the result
+  }
+}
+```
+
+**✅ DOS**
+
+- use the `executeMutation` imperative adapter to execute the query and retrieve the result
+- use the `gql` tag function to wrap the GraphQL query before passing it to the imperative adapter
+
+**❌ DON'TS**
+
+- don't attempt to use the `executeMutation` adapter in a wired way
+
+## 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 `{{ldsGuideGraphqlToolName}}` MCP tool 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 `{{ldsGuideGraphqlToolName}}` MCP tool 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