@salesforce/webapp-template-base-sfdx-project-experimental 1.112.5 → 1.112.7

package/.a4drules/skills/installing-webapp-features/SKILL.md

@@ -1,210 +0,0 @@
----
-name: installing-webapp-features
-description: Search, describe, and install pre-built UI features (authentication, shadcn components, navigation, search, GraphQL, Agentforce AI) into Salesforce webapps. Use this when the user wants to add functionality to a webapp, or when determining what salesforce-provided features are available — whether prompted by the user or on your own initiative. Always check for an existing feature before building from scratch.
----
-
-# webapps-features-experimental CLI — Agent Reference
-
-**Always check for an existing feature before building something yourself.** This CLI installs pre-built, tested feature packages into Salesforce webapps. Features range from foundational UI component libraries (shadcn/ui with Button, Card, Input, Table, etc.) to full-stack application capabilities like authentication (login, registration, password flows, session management, and Apex backend classes), global search, navigation menus, GraphQL integrations, and Agentforce AI conversation UIs. Each feature ships as a complete implementation — including React components, context providers, route guards, and any required Salesforce server-side code — that already handles platform-specific concerns like Salesforce API integration, session management, and SFDX metadata structure. Building these from scratch is error-prone and unnecessary when a feature exists. **If no existing feature is found, ask the user before proceeding with a custom implementation — a relevant feature may exist under a different name or keyword.**
-
-```
-npx @salesforce/webapps-features-experimental <command> [options]
-```
-
-## Workflow: Search Project → Search Features → Describe → Install
-
-**MANDATORY**: When the user asks to add ANY webapp functionality, follow this entire workflow. Do not skip steps.
-
-### 1. Search existing project code
-
-Before installing anything, check whether the functionality already exists in the **project source code** (not dependencies).
-
-- **Always scope searches to `src/`** to avoid matching files in `node_modules/`, `dist/`, or `build/` output
-- Use Glob with a scoped path: e.g., `src/**/Button.tsx`, `src/**/*auth*.tsx`
-- Use Grep with the `path` parameter set to the `src/` directory, or use `glob: "*.{ts,tsx}"` to restrict file types
-- Check common directories: `src/components/`, `src/lib/`, `src/pages/`, `src/hooks/`
-- **Never** search from the project root without a path or glob filter — this will crawl `node_modules` and produce massive, unhelpful output
-
-**If existing code is found** — read the files, present them to the user, and ask if they want to reuse or extend what's there. If yes, use the existing code and stop. If no, proceed to step 2.
-
-**If nothing is found** — proceed to step 2.
-
-### 2. Search available features
-
-```bash
-npx @salesforce/webapps-features-experimental list [options]
-```
-
-Options:
-
-- `-v, --verbose` — Show full descriptions, packages, and dependencies
-- `--search <query>` — Filter features by keyword (ranked by relevance)
-
-```bash
-npx @salesforce/webapps-features-experimental list
-npx @salesforce/webapps-features-experimental list --search "auth"
-npx @salesforce/webapps-features-experimental list --search "button"
-```
-
-**If no matching feature is found** — ask the user before proceeding with a custom implementation. A relevant feature may exist under a different name or keyword.
-
-### 3. Describe a feature
-
-```bash
-npx @salesforce/webapps-features-experimental describe <feature>
-```
-
-Shows description, package name, dependencies, components, copy operations, and example files.
-
-```bash
-npx @salesforce/webapps-features-experimental describe authentication
-npx @salesforce/webapps-features-experimental describe shadcn
-```
-
-### 4. Install a feature
-
-```bash
-npx @salesforce/webapps-features-experimental install <feature> --webapp-dir <path> [options]
-```
-
-Resolves the feature name to an npm package, installs it and its dependencies (including transitive feature dependencies like `shadcn`), copies source files into your project, and reports any `__example__` files that require manual integration.
-
-Options:
-
-- `--webapp-dir <name>` (required) — Webapp name, resolves to `<sfdx-source>/webapplications/<name>`
-- `--sfdx-source <path>` (default: `force-app/main/default`) — SFDX source directory
-- `--dry-run` (default: `false`) — Preview changes without writing files
-- `-v, --verbose` (default: `false`) — Enable verbose logging
-- `-y, --yes` (default: `false`) — Skip all prompts (auto-skip conflicts)
-- `--on-conflict <mode>` (default: `prompt`) — `prompt`, `error`, `skip`, or `overwrite`
-- `--conflict-resolution <file>` — Path to JSON file with per-file resolutions
-
-```bash
-# Install authentication (also installs shadcn dependency)
-npx @salesforce/webapps-features-experimental install authentication \
-  --webapp-dir mywebapp
-
-# Dry run to preview changes
-npx @salesforce/webapps-features-experimental install shadcn \
-  --webapp-dir mywebapp \
-  --dry-run
-
-# Non-interactive install (skip all file conflicts)
-npx @salesforce/webapps-features-experimental install authentication \
-  --webapp-dir mywebapp \
-  --yes
-```
-
-## Conflict Handling
-
-Since you are running in a non-interactive environment, you cannot use `--on-conflict prompt` directly. When conflicts are likely (e.g. installing into an existing project), you have two options:
-
-**Option A — Let the user resolve conflicts interactively.** Suggest the user run the install command themselves with `--on-conflict prompt` so they can decide per-file.
-
-**Option B — Two-pass automated resolution:**
-
-```bash
-# Pass 1: detect conflicts
-npx @salesforce/webapps-features-experimental install authentication \
-  --webapp-dir mywebapp \
-  --on-conflict error
-
-# The CLI will exit with an error listing every conflicting file path.
-
-# Pass 2: create a resolution file and re-run
-echo '{ "src/styles/global.css": "overwrite", "src/lib/utils.ts": "skip" }' > resolutions.json
-
-npx @salesforce/webapps-features-experimental install authentication \
-  --webapp-dir mywebapp \
-  --conflict-resolution resolutions.json
-```
-
-Resolution values per file: `"skip"` (keep existing) or `"overwrite"` (replace). When unsure how to resolve a conflict, ask the user rather than guessing.
-
-## Hint Placeholders in Copy Paths
-
-Some copy operations use **hint placeholders** in the `"to"` path — descriptive segments like `<desired-page-with-search-input>` that are NOT resolved by the CLI. These are guidance for the user or LLM to choose an appropriate destination.
-
-**How they work:** The file is copied with the literal placeholder name (e.g., `src/pages/<desired-page-with-search-input>.tsx`). After installation, you should:
-
-1. Read the copied file to understand its purpose
-2. Rename or relocate it to the intended target (e.g., `src/pages/Home.tsx`)
-3. Or integrate its patterns into an existing file, then delete it
-
-**How to identify them:** Hint placeholders use `<descriptive-name>` syntax but are NOT one of the system placeholders (`<sfdxSource>`, `<webappDir>`, `<webapp>`). They always appear in the middle or end of a path, never as the leading segment.
-
-**Example from features.json:**
-
-```json
-{
-  "to": "<webappDir>/src/pages/<desired-page-with-search-input>.tsx",
-  "description": "Example home page showing GlobalSearchInput integration",
-  "integrationTarget": "src/pages/Home.tsx"
-}
-```
-
-The `integrationTarget` field tells you the suggested destination. Use your judgment — if the user already has a different page where search should go, integrate there instead.
-
-**When `integrationTarget` itself is a placeholder:** Some features use a hint placeholder in the `integrationTarget` value (e.g., `"integrationTarget": "src/<path-to-desired-page-with-search-input>.tsx"`). This means there is no single default target — the user must decide which existing file to integrate into. When you encounter this:
-
-1. Ask the user which page or file they want to integrate the feature into
-2. Read the `__example__` file to understand the integration pattern
-3. Read the user's chosen target file
-4. Apply the pattern from the example into the target file
-
-## Post Installation: Integrating **example** Files
-
-Features may include `__example__` files (e.g., `__example__auth-app.tsx`) showing integration patterns.
-
-**The describe command shows**:
-
-- Which **example** files will be copied
-- Target file to integrate into (e.g., `src/app.tsx`)
-- What the example demonstrates
-
-### How to Integrate Example Files (CRITICAL FOR LLMs)
-
-⚠️ **ONLY USE Read AND Edit TOOLS - NO BASH COMMANDS** ⚠️
-
-**DO NOT DO THIS**:
-
-- ❌ `git status` or any git commands
-- ❌ `ls`, `cat`, `sed`, `awk`, or ANY bash file commands
-- ❌ Chaining bash commands to read multiple files
-- ❌ Using bash to check directories or file existence
-
-**DO THIS INSTEAD**:
-
-- ✅ Use Read tool with `file_path` parameter to read each file
-- ✅ Use Edit tool with `file_path`, `old_string`, `new_string` to modify files
-- ✅ That's it! Just Read and Edit tools.
-
-**Integration steps**:
-
-1. **Read each example file** (use Read tool)
-   - Example: Read tool with `file_path: "force-app/main/default/webapplications/mywebapp/src/__example__auth-app.tsx"`
-   - Note the imports and patterns to integrate
-
-2. **Read each target file** (use Read tool)
-   - Example: Read tool with `file_path: "force-app/main/default/webapplications/mywebapp/src/app.tsx"`
-   - Understand where the new code should go
-
-3. **Edit each target file** (use Edit tool)
-   - Add imports from the example
-   - Add or modify code following the example's patterns
-   - Preserve existing functionality
-
-4. **Delete the example file after successful integration** (use Bash tool)
-   - Example: `rm force-app/main/default/webapplications/mywebapp/src/__example__authentication-routes.tsx`
-   - Only delete after you have successfully integrated the pattern
-   - This keeps the codebase clean and removes temporary example files
-
-## Troubleshooting
-
-**Directory not found**: Check paths are correct, use absolute or correct relative paths
-
-**Feature not found**: Use `npx @salesforce/webapps-features-experimental list` to see available feature names
-
-**Conflicts in error mode**: Follow CLI instructions to create resolution file
-
-**Need help?**: Run `npx @salesforce/webapps-features-experimental --help` to see all commands and options

package/.a4drules/skills/using-salesforce-data/SKILL.md

@@ -1,363 +0,0 @@
----
-name: using-salesforce-data
-description: Salesforce data access for reading, writing, and querying records via REST, GraphQL, Apex, or Platform SDK. Use when the user wants to fetch, search, filter, sort, display, create, update, delete, or attach files to Salesforce records (standard objects like Accounts, Contacts, Opportunities, Cases, Quotes, or any custom object) in a web app or UI component (React, Angular, Vue, etc.); call Chatter, Connect, or Apex REST APIs; or invoke AuraEnabled Apex methods from an external app. Does not apply to authentication/OAuth setup, schema changes (adding fields, relationships), Bulk/Tooling/Metadata API usage, declarative automation (Flows, Process Builder), general LWC/Apex coding guidance without a specific data operation, or Salesforce admin/configuration tasks.
----
-
-# Salesforce Data Access
-
-## When to Use
-
-Use this skill when the user wants to:
-
-- **Fetch or display Salesforce data** — Query records (Account, Contact, Opportunity, custom objects) to show in a component
-- **Create, update, or delete records** — Perform mutations on Salesforce data
-- **Add data fetching to a component** — Wire up a React component to Salesforce data
-- **Call REST APIs** — Use Connect REST, Apex REST, or UI API endpoints
-- **Explore the org schema** — Discover available objects, fields, or relationships
-
-## Data SDK Requirement
-
-> **All Salesforce data access MUST use the Data SDK** (`@salesforce/sdk-data`). The SDK handles authentication, CSRF, and base URL resolution. Never use `fetch()` or `axios` directly.
-
-```typescript
-import { createDataSDK, gql } from "@salesforce/sdk-data";
-
-const sdk = await createDataSDK();
-
-// GraphQL for record queries/mutations (PREFERRED)
-const response = await sdk.graphql?.<ResponseType>(query, variables);
-
-// REST for Connect REST, Apex REST, UI API (when GraphQL insufficient)
-const res = await sdk.fetch?.("/services/apexrest/my-resource");
-```
-
-**Always use optional chaining** (`sdk.graphql?.()`, `sdk.fetch?.()`) — these methods may be undefined in some surfaces.
-
-## Supported APIs
-
-**Only the following APIs are permitted.** Any endpoint not listed here must not be used.
-
-| API | Method | Endpoints / Use Case |
-|-----|--------|----------------------|
-| GraphQL | `sdk.graphql` | All record queries and mutations via `uiapi { }` namespace |
-| UI API REST | `sdk.fetch` | `/services/data/v{ver}/ui-api/records/{id}` — record metadata when GraphQL is insufficient |
-| Apex REST | `sdk.fetch` | `/services/apexrest/{resource}` — custom server-side logic, aggregates, multi-step transactions |
-| Connect REST | `sdk.fetch` | `/services/data/v{ver}/connect/file/upload/config` — file upload config |
-| Einstein LLM | `sdk.fetch` | `/services/data/v{ver}/einstein/llm/prompt/generations` — AI text generation |
-
-**Not supported:**
-
-- **Enterprise REST query endpoint** (`/services/data/v*/query` with SOQL) — blocked at the proxy level. Use GraphQL for record reads; use Apex REST if server-side SOQL aggregates are required.
-- **Aura-enabled Apex** (`@AuraEnabled`) — an LWC/Aura pattern with no invocation path from React webapps.
-- **Chatter API** (`/chatter/users/me`) — use `uiapi { currentUser { ... } }` in a GraphQL query instead.
-- **Any other Salesforce REST endpoint** not listed in the supported table above.
-
-## Decision: GraphQL vs REST
-
-| Need | Method | Example |
-|------|--------|---------|
-| Query/mutate records | `sdk.graphql` | Account, Contact, custom objects |
-| Current user info | `sdk.graphql` | `uiapi { currentUser { Id Name { value } } }` |
-| UI API record metadata | `sdk.fetch` | `/ui-api/records/{id}` |
-| Connect REST | `sdk.fetch` | `/connect/file/upload/config` |
-| Apex REST | `sdk.fetch` | `/services/apexrest/auth/login` |
-| Einstein LLM | `sdk.fetch` | `/einstein/llm/prompt/generations` |
-
-**GraphQL is preferred** for record operations. Use REST only when GraphQL doesn't cover the use case.
-
----
-
-## GraphQL Workflow
-
-### Step 1: Acquire Schema
-
-The `schema.graphql` file (265K+ lines) is the source of truth. **Never open or parse it directly.**
-
-1. Check if `schema.graphql` exists at the SFDX project root
-2. If missing, run from the **webapp dir**: `npm run graphql:schema`
-3. Custom objects appear only after metadata is deployed
-
-### Step 2: Look Up Entity Schema
-
-Map user intent to PascalCase names ("accounts" → `Account`), then **run the search script from the project root**:
-
-```bash
-# From project root — look up all relevant schema info for one or more entities
-bash .a4drules/skills/using-salesforce-data/graphql-search.sh Account
-
-# Multiple entities at once
-bash .a4drules/skills/using-salesforce-data/graphql-search.sh Account Contact Opportunity
-```
-
-The script outputs five sections per entity:
-1. **Type definition** — all queryable fields and relationships
-2. **Filter options** — available fields for `where:` conditions
-3. **Sort options** — available fields for `orderBy:`
-4. **Create input** — fields accepted by create mutations
-5. **Update input** — fields accepted by update mutations
-
-Use this output to determine exact field names before writing any query or mutation. **Maximum 2 script runs.** If the entity still can't be found, ask the user — the object may not be deployed.
-
-### Step 3: Generate Query
-
-Use the templates below. Every field name **must** be verified from the script output in Step 2.
-
-#### Read Query Template
-
-```graphql
-query GetAccounts {
-  uiapi {
-    query {
-      Account(where: { Industry: { eq: "Technology" } }, first: 10) {
-        edges {
-          node {
-            Id
-            Name @optional { value }
-            Industry @optional { value }
-            # Parent relationship
-            Owner @optional { Name { value } }
-            # Child relationship
-            Contacts @optional {
-              edges { node { Name @optional { value } } }
-            }
-          }
-        }
-      }
-    }
-  }
-}
-```
-
-**FLS Resilience**: Apply `@optional` to all record fields. The server omits inaccessible fields instead of failing. Consuming code must use optional chaining:
-
-```typescript
-const name = node.Name?.value ?? "";
-```
-
-#### Mutation Template
-
-```graphql
-mutation CreateAccount($input: AccountCreateInput!) {
-  uiapi {
-    AccountCreate(input: $input) {
-      Record { Id Name { value } }
-    }
-  }
-}
-```
-
-**Mutation constraints:**
-- Create: Include required fields, only `createable` fields, no child relationships
-- Update: Include `Id`, only `updateable` fields
-- Delete: Include `Id` only
-
-#### Object Metadata & Picklist Values
-
-Use `uiapi { objectInfos(...) }` to fetch field metadata or picklist values. Pass **either** `apiNames` or `objectInfoInputs` — never both in the same query.
-
-**Object metadata** (field labels, data types, CRUD flags):
-
-```typescript
-const GET_OBJECT_INFO = gql`
-  query GetObjectInfo($apiNames: [String!]!) {
-    uiapi {
-      objectInfos(apiNames: $apiNames) {
-        ApiName
-        label
-        labelPlural
-        fields {
-          ApiName
-          label
-          dataType
-          updateable
-          createable
-        }
-      }
-    }
-  }
-`;
-
-const sdk = await createDataSDK();
-const response = await sdk.graphql?.(GET_OBJECT_INFO, { apiNames: ["Account"] });
-const objectInfos = response?.data?.uiapi?.objectInfos ?? [];
-```
-
-**Picklist values** (use `objectInfoInputs` + `... on PicklistField` inline fragment):
-
-```typescript
-const GET_PICKLIST_VALUES = gql`
-  query GetPicklistValues($objectInfoInputs: [ObjectInfoInput!]!) {
-    uiapi {
-      objectInfos(objectInfoInputs: $objectInfoInputs) {
-        ApiName
-        fields {
-          ApiName
-          ... on PicklistField {
-            picklistValuesByRecordTypeIDs {
-              recordTypeID
-              picklistValues {
-                label
-                value
-              }
-            }
-          }
-        }
-      }
-    }
-  }
-`;
-
-const response = await sdk.graphql?.(GET_PICKLIST_VALUES, {
-  objectInfoInputs: [{ objectApiName: "Account" }],
-});
-const fields = response?.data?.uiapi?.objectInfos?.[0]?.fields ?? [];
-```
-
-### Step 4: Validate & Test
-
-1. **Lint**: `npx eslint <file>` from webapp dir
-2. **Test**: Ask user before testing. For mutations, request input values — never fabricate data.
-
-**If ESLint reports a GraphQL error** (e.g. `Cannot query field`, `Unknown type`, `Unknown argument`), the field or type name is wrong. Re-run the schema search script to find the correct name — do not guess:
-
-```bash
-# From project root — re-check the entity that caused the error
-bash .a4drules/skills/using-salesforce-data/graphql-search.sh <EntityName>
-```
-
-Then fix the query using the exact names from the script output.
-
----
-
-## Webapp Integration (React)
-
-```typescript
-import { createDataSDK, gql } from "@salesforce/sdk-data";
-
-const GET_ACCOUNTS = gql`
-  query GetAccounts {
-    uiapi {
-      query {
-        Account(first: 10) {
-          edges {
-            node {
-              Id
-              Name @optional { value }
-              Industry @optional { value }
-            }
-          }
-        }
-      }
-    }
-  }
-`;
-
-const sdk = await createDataSDK();
-const response = await sdk.graphql?.(GET_ACCOUNTS);
-
-if (response?.errors?.length) {
-  throw new Error(response.errors.map(e => e.message).join("; "));
-}
-
-const accounts = response?.data?.uiapi?.query?.Account?.edges?.map(e => e.node) ?? [];
-```
-
----
-
-## REST API Patterns
-
-Use `sdk.fetch` when GraphQL is insufficient. See the [Supported APIs](#supported-apis) table for the full allowlist.
-
-```typescript
-declare const __SF_API_VERSION__: string;
-const API_VERSION = typeof __SF_API_VERSION__ !== "undefined" ? __SF_API_VERSION__ : "65.0";
-
-// Connect — file upload config
-const res = await sdk.fetch?.(`/services/data/v${API_VERSION}/connect/file/upload/config`);
-
-// Apex REST (no version in path)
-const res = await sdk.fetch?.("/services/apexrest/auth/login", {
-  method: "POST",
-  body: JSON.stringify({ email, password }),
-  headers: { "Content-Type": "application/json" },
-});
-
-// UI API — record with metadata (prefer GraphQL for simple reads)
-const res = await sdk.fetch?.(`/services/data/v${API_VERSION}/ui-api/records/${recordId}`);
-
-// Einstein LLM
-const res = await sdk.fetch?.(`/services/data/v${API_VERSION}/einstein/llm/prompt/generations`, {
-  method: "POST",
-  body: JSON.stringify({ promptTextorId: prompt }),
-});
-```
-
-**Current user**: Do not use Chatter (`/chatter/users/me`). Use GraphQL instead:
-
-```typescript
-const GET_CURRENT_USER = gql`
-  query CurrentUser {
-    uiapi { currentUser { Id Name { value } } }
-  }
-`;
-const response = await sdk.graphql?.(GET_CURRENT_USER);
-```
-
----
-
-## Directory Structure
-
-```
-<project-root>/                              ← SFDX project root
-├── schema.graphql                           ← grep target (lives here)
-├── sfdx-project.json
-└── force-app/main/default/webapplications/<app-name>/  ← webapp dir
-    ├── package.json                         ← npm scripts
-    └── src/
-```
-
-| Command | Run From | Why |
-|---------|----------|-----|
-| `npm run graphql:schema` | webapp dir | Script in webapp's package.json |
-| `npx eslint <file>` | webapp dir | Reads eslint.config.js |
-| `bash .a4drules/skills/using-salesforce-data/graphql-search.sh <Entity>` | project root | Schema lookup |
-| `sf api request rest` | project root | Needs sfdx-project.json |
-
----
-
-## Quick Reference
-
-### Schema Lookup (from project root)
-
-Run the search script to get all relevant schema info in one step:
-
-```bash
-bash .a4drules/skills/using-salesforce-data/graphql-search.sh <EntityName>
-```
-
-| Script Output Section | Used For |
-|-----------------------|----------|
-| Type definition | Field names, parent/child relationships |
-| Filter options | `where:` conditions |
-| Sort options | `orderBy:` |
-| CreateRepresentation | Create mutation field list |
-| UpdateRepresentation | Update mutation field list |
-
-### Error Categories
-
-| Error Contains | Resolution |
-|----------------|------------|
-| `Cannot query field` | Field name is wrong — run `graphql-search.sh <Entity>` and use the exact name from the Type definition section |
-| `Unknown type` | Type name is wrong — run `graphql-search.sh <Entity>` to confirm the correct PascalCase entity name |
-| `Unknown argument` | Argument name is wrong — run `graphql-search.sh <Entity>` and check Filter or OrderBy sections |
-| `invalid syntax` | Fix syntax per error message |
-| `validation error` | Field name is wrong — run `graphql-search.sh <Entity>` to verify |
-| `VariableTypeMismatch` | Correct argument type from schema |
-| `invalid cross reference id` | Entity deleted — ask for valid Id |
-
-### Checklist
-
-- [ ] All field names verified via search script (Step 2)
-- [ ] `@optional` applied to record fields (reads)
-- [ ] Optional chaining in consuming code
-- [ ] Lint passes: `npx eslint <file>`