@salesforce/webapp-template-feature-react-authentication-experimental 1.111.0 → 1.112.1

package/dist/.a4drules/skills/generating-graphql-read-query/SKILL.md

@@ -1,253 +0,0 @@
----
-name: generating-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`

package/dist/.a4drules/skills/using-graphql/SKILL.md

@@ -1,324 +0,0 @@
----
-name: using-graphql
-description: Salesforce GraphQL data access. Use when the user asks to fetch, query, or mutate Salesforce data, or add a GraphQL operation for an object like Account, Contact, or Opportunity.
-paths:
-  - "**/*.ts"
-  - "**/*.tsx"
-  - "**/*.graphql"
----
-
-# Salesforce GraphQL
-
-Guidance for querying and mutating Salesforce data via the Salesforce GraphQL API. Use `createDataSDK()` + `sdk.graphql?.()` and codegen tooling.
-
-## When to Use
-
-- User asks to "fetch data from Salesforce"
-- User asks to "query" or "mutate" Salesforce records
-- User wants to add a new GraphQL operation (query or mutation)
-- User asks to add data access for a Salesforce object (Account, Contact, Opportunity, etc.)
-
-## Schema Access Policy (GREP ONLY)
-
-> **GREP ONLY** — The `schema.graphql` file is very large (~265,000+ lines). 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.
-
-## Directory Context
-
-The generated app has a two-level directory structure. Commands must run from the correct directory.
-
-```
-<project-root>/                                            ← SFDX project root
-├── schema.graphql                                         ← grep target
-├── sfdx-project.json
-└── force-app/main/default/webapplications/<app-name>/     ← webapp dir
-    ├── package.json         (npm scripts: graphql:schema, graphql:codegen, lint)
-    ├── eslint.config.js     (schema ref: ../../../../../schema.graphql)
-    ├── codegen.yml          (schema ref: ../../../../../schema.graphql)
-    └── src/                 (source code, .graphql query files)
-```
-
-| Command                   | Run from         | Why                                    |
-| ------------------------- | ---------------- | -------------------------------------- |
-| `npm run graphql:schema`  | **webapp dir**   | Script is in webapp's `package.json`   |
-| `npm run graphql:codegen` | **webapp dir**   | Reads `codegen.yml` in webapp dir       |
-| `npx eslint <file>`      | **webapp dir**   | Reads `eslint.config.js` in webapp dir |
-| `grep ... schema.graphql` | **project root** | `schema.graphql` lives at project root |
-| `sf api request graphql` | **project root** | Needs `sfdx-project.json`              |
-
-> **Wrong directory = silent failures.** `npm run graphql:schema` from the project root will fail with "missing script." `grep ./schema.graphql` from the webapp dir will fail with "no such file."
-
-## Prerequisites
-
-The base React app (`base-react-app`) ships with all GraphQL dependencies and tooling pre-configured:
-
-- `@salesforce/sdk-data` — runtime SDK for `createDataSDK` and `gql`
-- `@graphql-codegen/cli` + plugins — type generation from `.graphql` files and inline `gql` queries
-- `@graphql-eslint/eslint-plugin` — validates `.graphql` files and `gql` template literals against `schema.graphql` (used as a query validation gate — see Step 6)
-- `graphql` — shared by codegen, ESLint, and schema introspection
-
-Before using this skill, ensure:
-
-1. The `@salesforce/sdk-data` package is available (provides `createDataSDK`, `gql`, `NodeOfConnection`)
-2. **Deployment order**: Metadata must be deployed before schema fetch; schema must be refetched after any metadata deployment. Invoke the `deploying-to-salesforce` skill when deploying or syncing with the org.
-3. A `schema.graphql` file exists at the project root. If missing, generate it:
-   ```bash
-   # Run from webapp dir (force-app/main/default/webapplications/<app-name>/)
-   npm run graphql:schema
-   ```
-
-## npm Scripts
-
-- **`npm run graphql:schema`** — _(run from webapp dir)_ Downloads the full GraphQL schema from a connected Salesforce org via introspection. Outputs `schema.graphql` to the project root.
-- **`npm run graphql:codegen`** — _(run from webapp dir)_ Generates TypeScript types from `.graphql` files and inline `gql` queries. Outputs to `src/api/graphql-operations-types.ts`.
-
-## Workflow
-
-### Step 1: Download Schema
-
-Ensure `schema.graphql` exists at the project root. If missing, run `npm run graphql:schema` from the webapp dir.
-
-### Step 2: Explore the Schema (grep-only)
-
-Before writing any query, verify the target object and its fields exist in the schema.
-
-**Invoke the `exploring-graphql-schema` skill** for the full exploration workflow and **mandatory grep-only access policy**.
-
-> **GREP ONLY** — All schema lookups MUST use the grep commands defined in the `exploring-graphql-schema` skill. Do NOT open, read, stream, or parse `./schema.graphql` with any tool other than grep.
-
-Key actions (all via grep):
-
-- `type <ObjectName> implements Record` — find available fields
-- `input <ObjectName>_Filter` — find filter options
-- `input <ObjectName>_OrderBy` — find sorting options
-- `input <ObjectName>CreateInput` / `<ObjectName>UpdateInput` — find mutation input types
-
-### Step 3: Choose the Query Pattern
-
-**Pattern 1 — External `.graphql` file** (recommended for complex queries):
-
-- Queries with variables, fragments, or shared across files
-- Full codegen support, syntax highlighting, shareable
-- Requires codegen step after changes
-- See example: `api/utils/accounts.ts` + `api/utils/query/highRevenueAccountsQuery.graphql`
-
-**Pattern 2 — Inline `gql` tag** (recommended for simple queries):
-
-- Simple queries without variables; colocated with usage code
-- Supports dynamic queries (field set varies at runtime)
-- **MUST use `gql` tag** — plain template strings bypass `@graphql-eslint` validation
-- See example: `api/utils/user.ts`
-
-### Step 4: Write the Query
-
-For **Pattern 1**:
-
-1. Create a `.graphql` file under `src/api/utils/query/`
-2. Follow UIAPI structure: `query { uiapi { query { ObjectName(...) { edges { node { ... } } } } } }`
-3. For mutations, invoke the `generating-graphql-mutation-query` skill
-4. For read queries, invoke the `generating-graphql-read-query` skill
-
-For **Pattern 2**:
-
-1. Define query inline using the `gql` template tag
-2. Ensure the query name matches what codegen expects
-
-### Step 5: Test Queries Against Live Org
-
-Use the testing workflows in the `generating-graphql-read-query` and `generating-graphql-mutation-query` skills to validate queries against the connected org before integrating into the app.
-
-### Step 6: Generate Types
-
-```bash
-# Run from webapp dir (force-app/main/default/webapplications/<app-name>/)
-npm run graphql:codegen
-```
-
-This updates `src/api/graphql-operations-types.ts` with `<OperationName>Query`/`<OperationName>Mutation` and `<OperationName>QueryVariables`/`<OperationName>MutationVariables`.
-
-### Step 7: Lint Validate
-
-Run ESLint on the file containing the query to validate it against the schema **before** any live testing:
-
-```bash
-# Run from webapp dir
-npx eslint <path-to-file>
-```
-
-The `@graphql-eslint/eslint-plugin` processor extracts GraphQL from `gql` template literals and validates them against `schema.graphql`. Fix all ESLint errors before proceeding.
-
-### Step 8: Implement and Verify
-
-Implement the data access function using the pattern below. Use the Quality Checklist before completing.
-
----
-
-## Core Types & Function Signatures
-
-### createDataSDK and graphql
-
-```typescript
-import { createDataSDK } from "@salesforce/sdk-data";
-
-const sdk = await createDataSDK();
-const response = await sdk.graphql?.<ResponseType, VariablesType>(query, variables);
-```
-
-`createDataSDK()` returns a `DataSDK` instance. The `graphql` method uses optional chaining (`?.`) because not all surfaces support GraphQL.
-
-### gql Template Tag
-
-```typescript
-import { gql } from "@salesforce/sdk-data";
-
-const MY_QUERY = gql`
-  query MyQuery {
-    uiapi { ... }
-  }
-`;
-```
-
-The `gql` tag enables ESLint validation against the schema. Plain template strings bypass validation.
-
-### Error Handling
-
-Default: treat any errors as failure (Strategy A). For partial data tolerance, log errors but use data. For mutations where some return fields are inaccessible, use Strategy C (fail only when no data).
-
-```typescript
-// Default: strict
-if (response?.errors?.length) {
-  throw new Error(response.errors.map((e) => e.message).join("; "));
-}
-const result = response?.data;
-```
-
-Responses follow `uiapi.query.ObjectName.edges[].node`; fields use `{ value }`.
-
-### NodeOfConnection
-
-```typescript
-import { type NodeOfConnection } from "@salesforce/sdk-data";
-
-type AccountNode = NodeOfConnection<GetHighRevenueAccountsQuery["uiapi"]["query"]["Account"]>;
-```
-
----
-
-## Pattern 1: External .graphql File
-
-Create a `.graphql` file, run `npm run graphql:codegen`, import with `?raw` suffix, and use generated types.
-
-**Required imports:**
-
-```typescript
-import { createDataSDK, type NodeOfConnection } from "@salesforce/sdk-data";
-import MY_QUERY from "./query/myQuery.graphql?raw"; // ← ?raw suffix required
-import type { GetMyDataQuery, GetMyDataQueryVariables } from "../graphql-operations-types";
-```
-
-**When to use:** Complex queries with variables, fragments, or shared across files. Does NOT support dynamic queries (field set varies at runtime).
-
----
-
-## Pattern 2: Inline gql Tag
-
-**Required imports:**
-
-```typescript
-import { createDataSDK, gql } from "@salesforce/sdk-data";
-import { type CurrentUserQuery } from "../graphql-operations-types";
-
-const MY_QUERY = gql`
-  query CurrentUser {
-    uiapi { ... }
-  }
-`;
-```
-
-> **MUST use `gql` tag** — plain template strings bypass the `@graphql-eslint` processor entirely, meaning no lint validation against the schema.
-
-**When to use:** Simple, colocated queries. Supports dynamic queries (field set varies at runtime).
-
----
-
-## Conditional Field Selection
-
-For dynamic fieldsets with **known** fields, use `@include(if: $condition)` and `@skip(if: $condition)` in `.graphql` files. See GraphQL spec for details.
-
----
-
-## Anti-Patterns (Not Recommended)
-
-### Direct API Calls
-
-```typescript
-// NOT RECOMMENDED: Direct axios/fetch calls for GraphQL
-// PREFERRED: Use the Data SDK
-const sdk = await createDataSDK();
-const response = await sdk.graphql?.<ResponseType>(query, variables);
-```
-
-### Missing Type Definitions
-
-```typescript
-// NOT RECOMMENDED: Untyped GraphQL calls
-// PREFERRED: Provide response type
-const response = await sdk.graphql?.<GetMyDataQuery>(query);
-```
-
-### Plain String Queries (Without gql Tag)
-
-```typescript
-// NOT RECOMMENDED: Plain strings bypass ESLint validation
-const query = `query { ... }`;
-
-// PREFERRED: Use gql tag for inline queries
-const QUERY = gql`query { ... }`;
-```
-
----
-
-## Quality Checklist
-
-> If you have not completed the workflow above, **stop and complete it first**. Invoke the skill workflow before using this checklist.
-
-Before completing GraphQL data access code:
-
-### For Pattern 1 (.graphql files):
-
-1. [ ] All field names verified via grep against `schema.graphql` (invoke `exploring-graphql-schema`)
-2. [ ] Create `.graphql` file for the query/mutation
-3. [ ] Run `npm run graphql:codegen` to generate types
-4. [ ] Import query with `?raw` suffix
-5. [ ] Import generated types from `graphql-operations-types.ts`
-6. [ ] Use `sdk.graphql?.<ResponseType>()` with proper generic
-7. [ ] Handle `response.errors` and destructure `response.data`
-8. [ ] Use `NodeOfConnection` for cleaner node types when needed
-9. [ ] Run `npx eslint <file>` from webapp dir — fix all GraphQL errors
-
-### For Pattern 2 (inline with gql):
-
-1. [ ] All field names verified via grep against `schema.graphql`
-2. [ ] Define query using `gql` template tag (NOT a plain string)
-3. [ ] Ensure query name matches generated types in `graphql-operations-types.ts`
-4. [ ] Import generated types for the query
-5. [ ] Use `sdk.graphql?.<ResponseType>()` with proper generic
-6. [ ] Handle `response.errors` and destructure `response.data`
-7. [ ] Run `npx eslint <file>` from webapp dir — fix all GraphQL errors
-
-### General:
-
-- [ ] Lint validation passes (`npx eslint <file>` reports no GraphQL errors)
-- [ ] Query field names match the schema exactly (case-sensitive, confirmed via grep)
-- [ ] Response type generic is provided to `sdk.graphql?.<T>()`
-- [ ] Optional chaining is used for nested response data
-
----
-
-## Reference
-
-- Schema exploration: invoke the `exploring-graphql-schema` skill
-- Read query generation: invoke the `generating-graphql-read-query` skill
-- Mutation query generation: invoke the `generating-graphql-mutation-query` skill
-- Shared GraphQL schema types: `shared-schema.graphqls` (in this skill directory)
-- Schema download: `npm run graphql:schema` (run from webapp dir)
-- Type generation: `npm run graphql:codegen` (run from webapp dir)