@salesforce/afv-skills 1.3.0 → 1.4.0

package/skills/using-webapp-salesforce-data/graphql-search.sh

@@ -0,0 +1,139 @@
+#!/usr/bin/env bash
+# graphql-search.sh — Look up one or more Salesforce entities in schema.graphql.
+#
+# Run from the SFDX project root (where schema.graphql lives):
+#   bash .a4drules/skills/using-salesforce-data/graphql-search.sh Account
+#   bash .a4drules/skills/using-salesforce-data/graphql-search.sh Account Contact Opportunity
+#
+# Pass a custom schema path with -s / --schema:
+#   bash .a4drules/skills/using-salesforce-data/graphql-search.sh -s /path/to/schema.graphql Account
+#   bash .a4drules/skills/using-salesforce-data/graphql-search.sh --schema ./other/schema.graphql Account Contact
+#
+# Output sections per entity:
+#   1. Type definition   — all fields and relationships
+#   2. Filter options    — <Entity>_Filter input (for `where:`)
+#   3. Sort options      — <Entity>_OrderBy input (for `orderBy:`)
+#   4. Create input      — <Entity>CreateRepresentation (for create mutations)
+#   5. Update input      — <Entity>UpdateRepresentation (for update mutations)
+
+SCHEMA="./schema.graphql"
+
+# ── Argument parsing ─────────────────────────────────────────────────────────
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    -s|--schema)
+      if [[ -z "${2-}" || "$2" == -* ]]; then
+        echo "ERROR: --schema requires a file path argument"
+        exit 1
+      fi
+      SCHEMA="$2"
+      shift 2
+      ;;
+    --)
+      shift
+      break
+      ;;
+    -*)
+      echo "ERROR: Unknown option: $1"
+      echo "Usage: bash $0 [-s <schema-path>] <EntityName> [EntityName2 ...]"
+      exit 1
+      ;;
+    *)
+      break
+      ;;
+  esac
+done
+
+if [ $# -eq 0 ]; then
+  echo "Usage: bash $0 [-s <schema-path>] <EntityName> [EntityName2 ...]"
+  echo "Example: bash $0 Account"
+  echo "Example: bash $0 Account Contact Opportunity"
+  echo "Example: bash $0 --schema /path/to/schema.graphql Account"
+  exit 1
+fi
+
+if [ ! -f "$SCHEMA" ]; then
+  echo "ERROR: schema.graphql not found at $SCHEMA"
+  echo "  Make sure you are running from the SFDX project root, or pass the path explicitly:"
+  echo "    bash $0 --schema <path/to/schema.graphql> <EntityName>"
+  echo "  If the file is missing entirely, generate it from the webapp dir:"
+  echo "    cd force-app/main/default/webapplications/<app-name> && npm run graphql:schema"
+  exit 1
+fi
+
+# ── Helper: extract lines from a grep match through the closing brace ────────
+# Prints up to MAX_LINES lines after (and including) the first match of PATTERN.
+# Uses a generous line count — blocks are always closed by a "}" line.
+
+extract_block() {
+  local label="$1"
+  local pattern="$2"
+  local max_lines="$3"
+
+  local match
+  match=$(grep -nE "$pattern" "$SCHEMA" | head -1)
+
+  if [ -z "$match" ]; then
+    echo "  (not found: $pattern)"
+    return
+  fi
+
+  echo "### $label"
+  grep -E "$pattern" "$SCHEMA" -A "$max_lines" | \
+    awk '/^\}$/{print; exit} {print}' | \
+    head -n "$max_lines"
+  echo ""
+}
+
+# ── Main loop ────────────────────────────────────────────────────────────────
+
+for ENTITY in "$@"; do
+  echo ""
+  echo "======================================================================"
+  echo "  SCHEMA LOOKUP: $ENTITY"
+  echo "======================================================================"
+  echo ""
+
+  # 1. Type definition — all fields and relationships
+  extract_block \
+    "Type definition — fields and relationships" \
+    "^type ${ENTITY} implements Record" \
+    200
+
+  # 2. Filter input — used in `where:` arguments
+  extract_block \
+    "Filter options — use in where: { ... }" \
+    "^input ${ENTITY}_Filter" \
+    100
+
+  # 3. OrderBy input — used in `orderBy:` arguments
+  extract_block \
+    "Sort options — use in orderBy: { ... }" \
+    "^input ${ENTITY}_OrderBy" \
+    60
+
+  # 4. Create mutation inputs
+  extract_block \
+    "Create mutation wrapper — ${ENTITY}CreateInput" \
+    "^input ${ENTITY}CreateInput" \
+    10
+
+  extract_block \
+    "Create mutation fields — ${ENTITY}CreateRepresentation" \
+    "^input ${ENTITY}CreateRepresentation" \
+    100
+
+  # 5. Update mutation inputs
+  extract_block \
+    "Update mutation wrapper — ${ENTITY}UpdateInput" \
+    "^input ${ENTITY}UpdateInput" \
+    10
+
+  extract_block \
+    "Update mutation fields — ${ENTITY}UpdateRepresentation" \
+    "^input ${ENTITY}UpdateRepresentation" \
+    100
+
+  echo ""
+done

package/skills/accessing-webapp-data/SKILL.md

@@ -1,178 +0,0 @@
----
-name: accessing-webapp-data
-description: Salesforce data access patterns. Use when adding or modifying any code that fetches data from Salesforce (records, Chatter, Connect API, etc.).
-paths:
-  - "**/*.ts"
-  - "**/*.tsx"
-  - "**/*.graphql"
----
-
-# Salesforce Data Access
-
-Guidance for accessing Salesforce data from web apps. **All Salesforce data fetches MUST use the Data SDK** (`@salesforce/sdk-data`). The SDK provides authentication, CSRF handling, and correct base URL resolution — direct `fetch` or `axios` calls bypass these and are not allowed.
-
-## Mandatory: Use the Data SDK
-
-> **Every Salesforce data fetch must go through the Data SDK.** Obtain it via `createDataSDK()`, then use `sdk.graphql?.()` or `sdk.fetch?.()`. Never call `fetch()` or `axios` directly for Salesforce endpoints.
-
-## Optional Chaining and Graceful Handling
-
-**Always use optional chaining** when calling `sdk.graphql` or `sdk.fetch` — these methods may be undefined in some surfaces (e.g., Salesforce ACC, MCP Apps). Handle the case where they are not available gracefully:
-
-```typescript
-const sdk = await createDataSDK();
-
-// ✅ Use optional chaining
-const response = await sdk.graphql?.(query);
-
-// ✅ Check before using fetch
-if (!sdk.fetch) {
-  throw new Error("Data SDK fetch is not available in this context");
-}
-const res = await sdk.fetch(url);
-```
-
-For GraphQL, if `sdk.graphql` is undefined, the call returns `undefined` — handle that in your logic (e.g., throw a clear error or return a fallback). For `sdk.fetch`, check availability before calling when the operation is required.
-
-## Preference: GraphQL First
-
-**GraphQL is the preferred method** for querying and mutating Salesforce records. Use it when:
-
-- Querying records (Account, Contact, Opportunity, custom objects)
-- Creating, updating, or deleting records (when GraphQL supports the operation)
-- Fetching related data, filters, sorting, pagination
-
-**Use `sdk.fetch` only when GraphQL is not sufficient.** For REST API usage, invoke the `fetching-rest-api` skill, which documents:
-
-- Chatter API (e.g., `/services/data/v65.0/chatter/users/me`)
-- Connect REST API (e.g., `/services/data/v65.0/connect/file/upload/config`)
-- Apex REST (e.g., `/services/apexrest/auth/login`)
-- UI API REST (e.g., `/services/data/v65.0/ui-api/records/{recordId}`)
-- Einstein LLM Gateway
-
----
-
-## Getting the SDK
-
-```typescript
-import { createDataSDK } from "@salesforce/sdk-data";
-
-const sdk = await createDataSDK();
-```
-
----
-
-## Example 1: GraphQL (Preferred)
-
-For record queries and mutations, use GraphQL via the Data SDK. Invoke the `using-graphql` skill for the full workflow (schema exploration, query authoring, codegen, lint validate).
-
-```typescript
-import { createDataSDK, gql } from "@salesforce/sdk-data";
-import type { GetAccountsQuery } from "../graphql-operations-types";
-
-const GET_ACCOUNTS = gql`
-  query GetAccounts {
-    uiapi {
-      query {
-        Account(first: 10) {
-          edges {
-            node {
-              Id
-              Name { value }
-            }
-          }
-        }
-      }
-    }
-  }
-`;
-
-export async function getAccounts() {
-  const sdk = await createDataSDK();
-  const response = await sdk.graphql?.<GetAccountsQuery>(GET_ACCOUNTS);
-
-  if (response?.errors?.length) {
-    throw new Error(response.errors.map((e) => e.message).join("; "));
-  }
-
-  return response?.data?.uiapi?.query?.Account?.edges?.map((e) => e?.node) ?? [];
-}
-```
-
----
-
-## Example 2: Fetch (When GraphQL Is Not Sufficient)
-
-For REST endpoints that have no GraphQL equivalent, use `sdk.fetch`. **Invoke the `fetching-rest-api` skill** for full documentation of Chatter, Connect REST, Apex REST, UI API REST, and Einstein LLM endpoints.
-
-```typescript
-import { createDataSDK } from "@salesforce/sdk-data";
-
-declare const __SF_API_VERSION__: string;
-const API_VERSION = typeof __SF_API_VERSION__ !== "undefined" ? __SF_API_VERSION__ : "65.0";
-
-export async function getCurrentUser() {
-  const sdk = await createDataSDK();
-  const response = await sdk.fetch?.(`/services/data/v${API_VERSION}/chatter/users/me`);
-
-  if (!response?.ok) throw new Error(`HTTP ${response?.status}`);
-  const data = await response.json();
-  return { id: data.id, name: data.name };
-}
-```
-
----
-
-## Anti-Patterns (Forbidden)
-
-### Direct fetch to Salesforce
-
-```typescript
-// ❌ FORBIDDEN — bypasses Data SDK auth and CSRF
-const res = await fetch("/services/data/v65.0/chatter/users/me");
-```
-
-### Direct axios to Salesforce
-
-```typescript
-// ❌ FORBIDDEN — bypasses Data SDK
-const res = await axios.get("/services/data/v65.0/chatter/users/me");
-```
-
-### Correct approach
-
-```typescript
-// ✅ CORRECT — use Data SDK
-const sdk = await createDataSDK();
-const res = await sdk.fetch?.("/services/data/v65.0/chatter/users/me");
-```
-
----
-
-## Clarifying Vague Data Requests
-
-When a user asks about data and the request is vague, **clarify before implementing**. Ask which of the following they want:
-
-- **Application code** — Add or modify code in a specific web app so the app performs the data interaction at runtime (e.g., GraphQL query in the React app)
-- **Local SF CLI** — Run Salesforce CLI commands locally (e.g., `sf data query`, `sf data import tree`) to interact with the org from the terminal
-- **Local example data** — Update or add local fixture/example data files (e.g., JSON in `data/`) for development or testing
-- **Other** — Data export, report generation, setup script, etc.
-
-Do not assume. A request like "fetch accounts" could mean: (1) add a GraphQL query to the app, (2) run `sf data query` in the terminal, or (3) update sample data files. Confirm the intent before proceeding.
-
----
-
-## Decision Flow
-
-1. **Need to query or mutate Salesforce records?** → Use GraphQL via the Data SDK. Invoke the `using-graphql` skill.
-2. **Need Chatter, Connect REST, Apex REST, UI API REST, or Einstein LLM?** → Use `sdk.fetch`. Invoke the `fetching-rest-api` skill.
-3. **Never** use `fetch`, `axios`, or similar directly for Salesforce API calls.
-
----
-
-## Reference
-
-- GraphQL workflow: invoke the `using-graphql` skill (`.a4drules/skills/using-graphql/`)
-- REST API via fetch: invoke the `fetching-rest-api` skill (`.a4drules/skills/fetching-rest-api/`)
-- Data SDK package: `@salesforce/sdk-data` (`createDataSDK`, `gql`, `NodeOfConnection`)
-- `createRecord` for UI API record creation: `@salesforce/webapp-experimental/api` (uses Data SDK internally)

package/skills/exploring-webapp-graphql-schema/SKILL.md

@@ -1,149 +0,0 @@
----
-name: exploring-webapp-graphql-schema
-description: Explore the Salesforce GraphQL schema via grep-only lookups. Use before generating any GraphQL query — schema exploration must complete first.
-paths:
-  - "**/*.ts"
-  - "**/*.tsx"
-  - "**/*.graphql"
----
-
-# Salesforce GraphQL Schema Exploration
-
-Guidance for AI agents working with the Salesforce GraphQL API schema. **GREP ONLY** — the schema file is very large (~265,000+ lines). All lookups MUST use grep; do NOT open, read, stream, or parse the file.
-
-## Deployment Prerequisites
-
-The schema reflects the **current org state**. Custom objects and fields appear only after metadata is deployed.
-
-- **Before** running `npm run graphql:schema`: Deploy all metadata (objects, permission sets, layouts) and assign the permission set to the target user. Invoke the `deploying-to-salesforce` skill for the full sequence.
-- **After** any metadata deployment: Re-run `npm run graphql:schema` and `npm run graphql:codegen` so types and queries stay in sync.
-
-## Schema File Location
-
-**Location:** `schema.graphql` at the **SFDX project root** (NOT inside the webapp dir). All grep commands **must be run from the project root** where `schema.graphql` lives.
-
-> ⚠️ **Important (Access Policy - GREP ONLY)**: Do NOT open, view, stream, paginate, or parse the schema with any tool other than grep. All lookups MUST be done via grep using anchored patterns with minimal context as defined below.
-
-If the file is not present, generate it by running (from the **webapp dir**, not the project root):
-
-```bash
-# Run from webapp dir (force-app/main/default/webapplications/<app-name>/)
-npm run graphql:schema
-```
-
-**BEFORE generating any GraphQL query, you MUST:**
-
-1. **Check if schema exists**: Look for `schema.graphql` in the **SFDX project root**
-2. **If schema is missing**:
-   - `cd` to the **webapp dir** and run `npm run graphql:schema` to download it
-   - Wait for the command to complete successfully
-   - Then proceed with grep-only lookups as defined below.
-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
-
-Main entry points: `Query { uiapi }` for reads; `Mutation { uiapi(input: ...) }` for creates/updates/deletes. Record queries use `uiapi.query.<ObjectName>`.
-
-## Allowed Lookups (grep-only)
-
-Use ONLY these grep commands to locate specific definitions in schema.graphql. Do not use editors (VS Code/vim/nano), cat/less/more/head/tail, or programmatic parsers (node/python/awk/sed/jq).
-
-- Always include:
-  - `-n` (line numbers) and `-E` (extended regex)
-  - Anchors (`^`) and word boundaries (`\b`)
-  - Minimal context with `-A N` (prefer the smallest N that surfaces the needed lines)
-
-### 1. Find Available Fields for a Record Type
-
-Search for `type <ObjectName> implements Record` to find all queryable fields:
-
-```bash
-# Example: Find Account fields (anchored, minimal context)
-grep -nE '^type[[:space:]]+Account[[:space:]]+implements[[:space:]]+Record\b' ./schema.graphql -A 60
-```
-
-### 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 (anchored)
-grep -nE '^input[[:space:]]+Account_Filter\b' ./schema.graphql -A 40
-```
-
-### 3. Find OrderBy Options
-
-Search for `input <ObjectName>_OrderBy` for sorting options:
-
-```bash
-# Example: Find Account ordering options (anchored)
-grep -nE '^input[[:space:]]+Account_OrderBy\b' ./schema.graphql -A 30
-```
-
-### 4. Find Mutation Operations
-
-Search for operations in `UIAPIMutations`:
-
-```bash
-# Example: Find Account mutations (extended regex)
-grep -nE 'Account.*(Create|Update|Delete)' ./schema.graphql
-```
-
-### 5. Find Input Types for Mutations
-
-Search for `input <ObjectName>CreateInput` or `input <ObjectName>UpdateInput`:
-
-```bash
-# Example: Find Account create input (anchored)
-grep -nE '^input[[:space:]]+AccountCreateInput\b' ./schema.graphql -A 30
-```
-
-## Agent Workflow for Building Queries (grep-only)
-
-**Pre-requisites (MANDATORY):**
-
-- [ ] Verified `schema.graphql` exists in the **SFDX project root**
-- [ ] If missing, ran `npm run graphql:schema` from the **webapp dir** 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. **Run the "Find Available Fields" grep command** for your object (copy only the field names visible in the grep output; do not open the file)
-3. **Run the "Find Filter Options" grep command** (`<Object>_Filter`) to understand filtering options
-4. **Run the "Find OrderBy Options" grep command** (`<Object>_OrderBy`) for sorting capabilities
-5. **Build the query** following the patterns in the `generating-graphql-read-query` or `generating-graphql-mutation-query` skill using only values returned by grep
-6. **Validate field names** using grep matches (case-sensitive). Do not open or parse the file beyond grep.
-
-## Tips for Agents
-
-- **Always verify field names** by running the specific grep commands; do not open the schema file
-- **Use grep with anchors and minimal -A context** to explore the schema efficiently—never read or stream the file
-- **Check relationships** by looking for `parentRelationship` and `childRelationship` comments in type definitions
-- **Look for Connection types** (e.g., `AccountConnection`) via grep to understand pagination structure
-- **Custom objects** end with `__c` (e.g., `CustomObject__c`)
-- **Custom fields** also end with `__c` (e.g., `Custom_Field__c`)
-
-## Forbidden Operations
-
-To prevent accidental large reads, the following are prohibited for schema.graphql:
-
-- Opening in any editor (VS Code, vim, nano)
-- Using cat, less, more, head, or tail
-- Programmatic parsing (node, python, awk, sed, jq)
-- Streaming or paginating through large portions of the file
-
-If any of the above occurs, stop and replace the action with one of the Allowed Lookups (grep-only).
-
-## Output Minimization
-
-- Prefer precise, anchored patterns with word boundaries
-- Use the smallest `-A` context that surfaces required lines
-- If results are noisy, refine the regex rather than increasing context
-
-## Related Skills
-
-- For generating read queries, invoke the `generating-graphql-read-query` skill
-- For generating mutation queries, invoke the `generating-graphql-mutation-query` skill

package/skills/fetching-webapp-rest-api/SKILL.md

@@ -1,167 +0,0 @@
----
-name: fetching-webapp-rest-api
-description: REST API usage via the Data SDK fetch method. Use when implementing Chatter, Connect REST, Apex REST, UI API REST, or Einstein LLM calls — only when GraphQL is not sufficient.
-paths:
-  - "**/*.ts"
-  - "**/*.tsx"
-  - "**/*.graphql"
----
-
-# Salesforce REST API via Data SDK Fetch
-
-Use `sdk.fetch` from the Data SDK when GraphQL is not sufficient. The SDK applies authentication, CSRF handling, and base URL resolution. **Always use optional chaining** (`sdk.fetch?.()`) and handle the case where `fetch` is not available.
-
-Invoke this skill when you need to call Chatter, Connect REST, Apex REST, UI API REST, or Einstein LLM endpoints.
-
-## API Version
-
-Use the project's API version. It is typically injected as `__SF_API_VERSION__`; fallback to `"65.0"`:
-
-```typescript
-declare const __SF_API_VERSION__: string;
-const API_VERSION = typeof __SF_API_VERSION__ !== "undefined" ? __SF_API_VERSION__ : "65.0";
-```
-
-## Base Path
-
-URLs are relative to the Salesforce API base. The SDK prepends the correct base path. Use paths starting with `/services/...`.
-
----
-
-## Chatter API
-
-User and collaboration data. No GraphQL equivalent.
-
-| Endpoint | Method | Purpose |
-| -------- | ------ | ------- |
-| `/services/data/v{version}/chatter/users/me` | GET | Current user (id, name, email, username) |
-
-```typescript
-const sdk = await createDataSDK();
-const response = await sdk.fetch?.(`/services/data/v${API_VERSION}/chatter/users/me`);
-
-if (!response?.ok) throw new Error(`HTTP ${response?.status}`);
-const data = await response.json();
-return { id: data.id, name: data.name };
-```
-
----
-
-## Connect REST API
-
-File and content operations.
-
-| Endpoint | Method | Purpose |
-| -------- | ------ | ------- |
-| `/services/data/v{version}/connect/file/upload/config` | GET | Upload config (token, uploadUrl) for file uploads |
-
-```typescript
-const sdk = await createDataSDK();
-const configRes = await sdk.fetch?.(`/services/data/v${API_VERSION}/connect/file/upload/config`, {
-  method: "GET",
-});
-
-if (!configRes?.ok) throw new Error(`Failed to get upload config: ${configRes?.status}`);
-const config = await configRes.json();
-const { token, uploadUrl } = config;
-```
-
----
-
-## Apex REST
-
-Custom Apex REST resources. Requires corresponding Apex classes in the org. CSRF protection is applied automatically for `services/apexrest` URLs.
-
-| Endpoint | Method | Purpose |
-| -------- | ------ | ------- |
-| `/services/apexrest/auth/login` | POST | User login |
-| `/services/apexrest/auth/register` | POST | User registration |
-| `/services/apexrest/auth/forgot-password` | POST | Request password reset |
-| `/services/apexrest/auth/reset-password` | POST | Reset password with token |
-| `/services/apexrest/auth/change-password` | POST | Change password (authenticated) |
-| `/services/apexrest/{resource}` | GET/POST | Custom Apex REST resources |
-
-**Example (login):**
-
-```typescript
-const sdk = await createDataSDK();
-const response = await sdk.fetch?.("/services/apexrest/auth/login", {
-  method: "POST",
-  body: JSON.stringify({ email, password, startUrl: "/" }),
-  headers: { "Content-Type": "application/json", Accept: "application/json" },
-});
-```
-
-Apex REST paths do not include the API version.
-
----
-
-## UI API (REST)
-
-When GraphQL cannot cover the use case. **Prefer GraphQL** when possible.
-
-| Endpoint | Method | Purpose |
-| -------- | ------ | ------- |
-| `/services/data/v{version}/ui-api/records/{recordId}` | GET | Fetch a single record |
-
-```typescript
-const sdk = await createDataSDK();
-const response = await sdk.fetch?.(`/services/data/v${API_VERSION}/ui-api/records/${recordId}`);
-```
-
----
-
-## Einstein LLM Gateway
-
-AI features. Requires Einstein API setup.
-
-| Endpoint | Method | Purpose |
-| -------- | ------ | ------- |
-| `/services/data/v{version}/einstein/llm/prompt/generations` | POST | Generate text from Einstein LLM |
-
-```typescript
-const sdk = await createDataSDK();
-const response = await sdk.fetch?.(`/services/data/v${API_VERSION}/einstein/llm/prompt/generations`, {
-  method: "POST",
-  headers: { "Content-Type": "application/json" },
-  body: JSON.stringify({
-    additionalConfig: { applicationName: "PromptTemplateGenerationsInvocable" },
-    promptTextorId: prompt,
-  }),
-});
-
-if (!response?.ok) throw new Error(`Einstein LLM failed (${response?.status})`);
-const data = await response.json();
-return data?.generations?.[0]?.text ?? "";
-```
-
----
-
-## General Pattern
-
-```typescript
-import { createDataSDK } from "@salesforce/sdk-data";
-
-const sdk = await createDataSDK();
-
-if (!sdk.fetch) {
-  throw new Error("Data SDK fetch is not available in this context");
-}
-
-const response = await sdk.fetch(url, {
-  method: "GET", // or POST, PUT, PATCH, DELETE
-  headers: { "Content-Type": "application/json", Accept: "application/json" },
-  body: method !== "GET" ? JSON.stringify(payload) : undefined,
-});
-
-if (!response.ok) throw new Error(`HTTP ${response.status}`);
-const data = await response.json();
-```
-
----
-
-## Reference
-
-- Parent: `accessing-data` — enforces Data SDK usage for all Salesforce data fetches
-- GraphQL: `using-graphql` — use for record queries and mutations when possible
-- `createRecord` from `@salesforce/webapp-experimental/api` for UI API record creation (uses SDK internally)