@salesforce/afv-skills 1.3.0 → 1.4.0

package/skills/generating-webapp-graphql-mutation-query/SKILL.md

@@ -1,258 +0,0 @@
----
-name: generating-webapp-graphql-mutation-query
-description: Generate Salesforce GraphQL mutation queries. Use when the query to generate is a mutation query. Schema exploration must complete first — invoke exploring-graphql-schema first.
-paths:
-  - "**/*.ts"
-  - "**/*.tsx"
-  - "**/*.graphql"
----
-
-# Salesforce GraphQL Mutation Query Generation
-
-**Triggering conditions**
-
-1. Only if the schema exploration phase completed successfully (invoke `exploring-graphql-schema` first)
-2. Only if the query to generate is a mutation query
-
-## Schema Access Policy
-
-> ⚠️ **GREP ONLY** — During mutation generation you may need to verify field names, input types, or representations. All schema lookups **MUST** use the grep-only commands defined in the `exploring-graphql-schema` skill. Do NOT open, read, stream, or parse `./schema.graphql` with any tool other than grep.
-
-## Your Role
-
-You are a GraphQL expert. Generate Salesforce-compatible mutation queries. Schema exploration must complete first. If the schema exploration has not been executed yet, you **MUST** run the full exploration workflow from the `exploring-graphql-schema` skill first, then return here for mutation query generation.
-
-## Mutation Queries General Information
-
-The GraphQL engine supports `Create`, `Update`, and `Delete` operations. `Update` and `Delete` operate on Id-based entity identification. See 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). Verify every field name and type against grep output from the schema — do NOT guess or assume
-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. Verify types via grep lookup — do NOT assume types
-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. **Field Name Validation** - Every field name in the generated mutation **MUST** match a field confirmed via grep lookup in the schema. Do NOT guess or assume field names exist
-8. **Query Generation** - Use the [mutation query](#mutation-query-templates) template and adjust it based on the selected operation
-9. **Output Format** - Use the [standalone](#mutation-standalone-default-output-format---clean-code-only)
-10. **Lint Validation** - After writing the mutation to a file, run `npx eslint <file>` from the webapp dir to validate it against the schema. Fix any reported errors before proceeding. See [Lint Validation](#lint-validation) for details
-11. **Test the Query** - Use the [Generated Mutation Query Testing](#generated-mutation-query-testing) workflow to test the generated query
-    1. **Report First** - Always output the generated mutation in the proper output format BEFORE initiating any test
-
-## 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 '@salesforce/sdk-data';
-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
-  }
-};
-```
-
-**❌ FORBIDDEN — Do NOT include any of the following:**
-
-- Explanatory comments about the query (inline or surrounding)
-- Field descriptions or annotations
-- Additional text about what the query does
-- Workflow step descriptions or summaries
-- Comments like `// fetches...`, `// creates...`, `/* ... */`
-
-**✅ ONLY output:**
-
-- The raw query string constant (using `gql` tagged template)
-- The variables object constant
-- Nothing else — no extra imports, no exports, no wrapper functions
-
-## Lint Validation
-
-After writing the generated mutation into a source file, validate it against the schema using the project's GraphQL ESLint setup:
-
-```bash
-# Run from webapp dir (force-app/main/default/webapplications/<app-name>/)
-npx eslint <path-to-file-containing-mutation>
-```
-
-**How it works:** The ESLint config uses `@graphql-eslint/eslint-plugin` with its `processor`, which extracts GraphQL operations from `gql` template literals in `.ts`/`.tsx` files and validates the extracted `.graphql` virtual files against `schema.graphql`.
-
-**Rules enforced:** `no-anonymous-operations`, `no-duplicate-fields`, `known-fragment-names`, `no-undefined-variables`, `no-unused-variables`
-
-**On failure:** Fix the reported issues, re-run `npx eslint <file>` until clean, then proceed to testing.
-
-> ⚠️ **Prerequisites**: The `schema.graphql` file must exist (invoke `exploring-graphql-schema` first) and project dependencies must be installed (`npm install`).
-
-## Generated Mutation Query Testing
-
-**Triggering conditions** — **ALL conditions must be true:**
-
-1. The [Mutation Query Generation Workflow](#mutation-query-generation-workflow) completed with status `SUCCESS` and you have a generated query
-2. The query is a mutation query
-3. A non-manual method was used during schema exploration to retrieve introspection data
-
-**Workflow**
-
-1. **Report Step** - State the exact method you will use to test (e.g., `sf api request graphql` from the **project root**, Connect API, etc.) — this **MUST** match the method used during schema exploration
-2. **Interactive Step** - Ask the user whether they want you to test the query using the proposed method
-   1. **STOP and WAIT** for the user's answer. Do NOT proceed until the user responds. Do NOT assume consent.
-3. **Input Arguments** - You **MUST** ask the user for the input argument values to use in the test
-   1. **STOP and WAIT** for the user's answer. Do NOT proceed until the user provides values. Do NOT fabricate test data.
-4. **Test Query** - Only if the user explicitly agrees and has provided input values:
-   1. Execute the mutation using the reported method (e.g., `sf api request rest` to POST the query and variables to the GraphQL endpoint):
-      ```bash
-      sf api request rest /services/data/v65.0/graphql \
-        --method POST \
-        --body '{"query":"mutation mutateEntity($input: EntityNameOperationInput!) { uiapi { EntityNameOperation(input: $input) { Record { Id } } } }","variables":{"input":{"EntityName":{"Field":"Value"}}}}'
-      ```
-   2. Replace `v65.0` with the API version of the target org
-   3. Replace the `query` value with the generated mutation query string
-   4. Replace the `variables` value with the user-provided input arguments
-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. **STOP and WAIT** for the user to provide a valid Id
-   - **Syntax** - Update the query using the error message information to fix the syntax errors
-   - **Validation** - The field name is most probably invalid. Re-run the relevant grep command from the `exploring-graphql-schema` skill to verify the correct field name. If still unclear, ask the user for clarification and **STOP and WAIT** for their answer
-   - **Type** - Use the error details and re-verify the type via grep lookup in the schema. Correct the argument 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 from the `exploring-graphql-schema` skill
-
-### `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. **STOP and WAIT** for the user's answer. Do NOT remove fields without explicit consent.
-6. If they are OK with removing the fields restart the [generation workflow](#mutation-query-generation-workflow) with the new field list
-
-## Related Skills
-
-- Schema exploration: `exploring-graphql-schema` (must complete first)
-- Read query generation: `generating-graphql-read-query`

package/skills/generating-webapp-graphql-read-query/SKILL.md

@@ -1,253 +0,0 @@
----
-name: generating-webapp-graphql-read-query
-description: Generate Salesforce GraphQL read queries. Use when the query to generate is a read query. Schema exploration must complete first — invoke exploring-graphql-schema first.
-paths:
-  - "**/*.ts"
-  - "**/*.tsx"
-  - "**/*.graphql"
----
-
-# Salesforce GraphQL Read Query Generation
-
-**Triggering conditions**
-
-1. Only if the schema exploration phase completed successfully (invoke `exploring-graphql-schema` first)
-2. Only if the query to generate is a read query
-
-## Schema Access Policy
-
-> ⚠️ **GREP ONLY** — During query generation you may need to verify field names, types, or relationships. All schema lookups **MUST** use the grep-only commands defined in the `exploring-graphql-schema` skill. Do NOT open, read, stream, or parse `./schema.graphql` with any tool other than grep.
-
-## Field-Level Security and @optional
-
-Field-level security (FLS) restricts which fields different users can see. Use the `@optional` directive on Salesforce record fields when possible. The server omits the field when the user lacks access, allowing the query to succeed instead of failing. Apply `@optional` to scalar fields, value-type fields (e.g. `Name { value }`), parent relationships, and child relationships. Available in API v65.0+.
-
-**Consuming code must defend against missing fields.** When a field is omitted due to FLS, it will be `undefined` (or absent) in the response. Use optional chaining (`?.`), nullish coalescing (`??`), and explicit null/undefined checks when reading query results. Never assume an optional field is present — otherwise the app may crash or behave incorrectly for users without field access.
-
-```ts
-// ✅ Defend against missing fields
-const name = node.Name?.value ?? '';
-const relatedName = node.RelationshipName?.Name?.value ?? 'N/A';
-
-// ❌ Unsafe — will throw if field omitted due to FLS
-const name = node.Name.value;
-```
-
-## Your Role
-
-You are a GraphQL expert. Generate Salesforce-compatible read queries. Schema exploration must complete first. If the schema exploration has not been executed yet, you **MUST** run the full exploration workflow from the `exploring-graphql-schema` skill first, then return here for read query generation.
-
-## 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. Do NOT add fields the user did not ask for.
-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. Verify types against grep output from the schema — do not assume types
-6. **Type Enforcement** - Make sure to leverage field type information from introspection and GraphQL schema to generate field access
-7. **Field Name Validation** - Every field name in the generated query **MUST** match a field confirmed via grep lookup in the schema. Do NOT guess or assume field names exist
-8. **@optional for FLS** - Apply `@optional` on all Salesforce record fields when possible (see [Field-Level Security and @optional](#field-level-security-and-optional)). This lets the query succeed when the user lacks field-level access; the server omits inaccessible fields instead of failing
-9. **Consuming code defense** - When generating or modifying code that consumes read query results, defend against missing fields (see [Field-Level Security and @optional](#field-level-security-and-optional)). Use optional chaining, nullish coalescing, and null/undefined checks — never assume optional fields are present
-10. **Semi and anti joins** - Use the semi-join or anti-join templates to filter an entity with conditions on child entities
-11. **Query Generation** - Use the [template](#read-query-template) to generate the query
-12. **Output Format** - Use the [standalone](#read-standalone-default-output-format---clean-code-only)
-13. **Lint Validation** - After writing the query to a file, run `npx eslint <file>` from the webapp dir to validate it against the schema. Fix any reported errors before proceeding. See [Lint Validation](#lint-validation) for details
-14. **Test the Query** - Use the [Generated Read Query Testing](#generated-read-query-testing) workflow to test the generated query
-    1. **Report First** - Always output the generated query in the proper output format BEFORE initiating any test
-
-## Read Query Template
-
-```graphql
-query QueryName {
-  uiapi {
-    query {
-      EntityName(
-        # conditions here
-      ) {
-        edges {
-          node {
-            # Direct fields — use @optional for FLS resilience
-            FieldName @optional { value }
-
-            # Non-polymorphic reference (single type)
-            RelationshipName @optional {
-              Id
-              Name { value }
-            }
-
-            # Polymorphic reference (multiple types)
-            PolymorphicRelationshipName @optional {
-              ...TypeAInfo
-              ...TypeBInfo
-            }
-
-            # Child relationship (subquery)
-            RelationshipName @optional (
-              # conditions here
-            ) {
-              edges {
-                node {
-                  # fields
-                }
-              }
-            }
-          }
-        }
-      }
-    }
-  }
-}
-
-fragment TypeAInfo on TypeA {
-  Id
-  SpecificFieldA @optional { value }
-}
-
-fragment TypeBInfo on TypeB {
-  Id
-  SpecificFieldB @optional { 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 @optional {
-              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
-};
-```
-
-**❌ FORBIDDEN — Do NOT include any of the following:**
-
-- Explanatory comments about the query (inline or surrounding)
-- Field descriptions or annotations
-- Additional text about what the query does
-- Workflow step descriptions or summaries
-- Comments like `// fetches...`, `// returns...`, `/* ... */`
-
-**✅ ONLY output:**
-
-- The raw query string constant
-- The variables object constant
-- Nothing else — no imports, no exports, no wrapper functions
-
-## Lint Validation
-
-After writing the generated query into a source file, validate it against the schema using the project's GraphQL ESLint setup:
-
-```bash
-# Run from webapp dir (force-app/main/default/webapplications/<app-name>/)
-npx eslint <path-to-file-containing-query>
-```
-
-**How it works:** The ESLint config uses `@graphql-eslint/eslint-plugin` with its `processor`, which extracts GraphQL operations from `gql` template literals in `.ts`/`.tsx` files and validates the extracted `.graphql` virtual files against `schema.graphql`.
-
-**Rules enforced:** `no-anonymous-operations`, `no-duplicate-fields`, `known-fragment-names`, `no-undefined-variables`, `no-unused-variables`
-
-**On failure:** Fix the reported issues, re-run `npx eslint <file>` until clean, then proceed to testing.
-
-> ⚠️ **Prerequisites**: The `schema.graphql` file must exist (invoke `exploring-graphql-schema` first) and project dependencies must be installed (`npm install`).
-
-## Generated Read Query Testing
-
-**Triggering conditions** — **ALL conditions must be true:**
-
-1. The [Read Query Generation Workflow](#read-query-generation-workflow) completed with status `SUCCESS` and you have a generated query
-2. The query is a read query
-3. A non-manual method was used during schema exploration to retrieve introspection data
-
-**Workflow**
-
-1. **Report Step** - State the exact method you will use to test (e.g., `sf api request graphql` from the **project root**, Connect API, etc.) — this **MUST** match the method used during schema exploration
-2. **Interactive Step** - Ask the user whether they want you to test the query using the proposed method
-   1. **STOP and WAIT** for the user's answer. Do NOT proceed until the user responds. Do NOT assume consent.
-3. **Test Query** - Only if the user explicitly agrees:
-   1. Use `sf api request rest` to POST the query to the GraphQL endpoint:
-      ```bash
-      sf api request rest /services/data/v65.0/graphql \
-        --method POST \
-        --body '{"query":"query GetData { uiapi { query { EntityName { edges { node { Id } } } } } }"}'
-      ```
-   2. Replace `v65.0` with the API version of the target org
-   3. Replace the `query` value with the generated read query string
-   4. If the query uses variables, include them in the JSON body as a `variables` key
-   5. Report the result as `SUCCESS` if the query executed without error, or `FAILED` if errors were returned
-   6. An empty result set with no errors is `SUCCESS` — the query is valid, the org simply has no matching data
-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** - The field name is most probably invalid. Re-run the relevant grep command from the `exploring-graphql-schema` skill to verify the correct field name. If still unclear, ask the user for clarification and **STOP and WAIT** for their answer
-   - **Type** - Use the error details and re-verify the type via grep lookup in the schema. Correct the argument 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 from the `exploring-graphql-schema` skill
-
-## Related Skills
-
-- Schema exploration: `exploring-graphql-schema` (must complete first)
-- Mutation generation: `generating-graphql-mutation-query`