@salesforce/afv-skills 1.5.0 → 1.5.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesforce/afv-skills",
-  "version": "1.5.0",
+  "version": "1.5.1",
   "description": "Salesforce skills for Agentforce Vibes",
   "license": "CC-BY-NC-4.0",
   "files": [
@@ -11,8 +11,8 @@
     "registry": "https://registry.npmjs.org"
   },
   "devDependencies": {
-    "@salesforce/webapp-template-app-react-sample-b2e-experimental": "^1.112.7",
-    "@salesforce/webapp-template-app-react-sample-b2x-experimental": "^1.112.7",
+    "@salesforce/webapp-template-app-react-sample-b2e-experimental": "^1.116.6",
+    "@salesforce/webapp-template-app-react-sample-b2x-experimental": "^1.116.6",
     "@types/js-yaml": "^4.0.9",
     "js-yaml": "^4.1.1",
     "tsx": "^4.21.0"

package/skills/creating-webapp/SKILL.md

@@ -1,8 +1,6 @@
 ---
 name: creating-webapp
 description: "Use this skill when creating or setting up a new SFDX React web application. Covers first steps, npm install, skills-first protocol, deployment order, and core web app rules."
-paths:
-  - "**/webapplications/**/*"
 ---
 
 # First Steps (MUST FOLLOW)

package/skills/generating-apex/SKILL.md

@@ -0,0 +1,253 @@
+---
+name: generating-apex
+description: Generate production-ready Apex classes for Salesforce following enterprise best practices. Covers service, selector, domain, batch, queueable, schedulable, DTO, utility, interface, abstract, and custom exception classes. Use this skill when the user asks to create, build, generate, scaffold, or refactor an Apex class. SCOPE Apex classes only — does not apply to triggers or unit tests.
+---
+
+# Apex Class
+
+Generate well-structured, production-ready Apex classes for Salesforce development.
+
+## Scope
+
+**Generates:**
+- Service classes (business logic layer)
+- Selector / query classes (SOQL encapsulation)
+- Domain classes (SObject-specific logic)
+- Batch Apex classes (`Database.Batchable`)
+- Queueable Apex classes (`Queueable`, optionally `Finalizer`)
+- Schedulable Apex classes (`Schedulable`)
+- DTO / wrapper / request-response classes
+- Utility / helper classes
+- Custom exception classes
+- Interfaces and abstract classes
+
+**Does NOT generate:**
+- Triggers (use a trigger framework skill)
+- Unit tests (use a test writer skill)
+- Aura controllers
+- LWC JavaScript controllers
+
+---
+
+## Gathering Requirements
+
+Before generating code, gather these inputs from the user (ask if not provided):
+
+1. **Class type** — Service, Selector, Batch, Queueable, Schedulable, Domain, DTO, Utility, Interface, Abstract, Exception
+2. **Class name** — or enough context to derive a meaningful name
+3. **SObject(s) involved** — if applicable
+4. **Business requirements** — plain-language description of what the class should do
+5. **Optional preferences:**
+   - Sharing model (`with sharing`, `without sharing`, `inherited sharing`)
+   - Access modifier (`public` or `global`)
+   - API version (default: `62.0`)
+   - Whether to include ApexDoc comments (default: yes)
+
+If the user provides a clear, complete request, generate immediately without unnecessary back-and-forth.
+
+---
+
+## Code Standards — ALWAYS Follow These
+
+### Separation of Concerns
+- **Service classes** contain business logic. They call Selectors for data and may call Domain classes for SObject-specific behavior.
+- **Selector classes** encapsulate all SOQL queries. Services never contain inline SOQL.
+- **Domain classes** encapsulate SObject-specific logic (field defaults, validation, transformation).
+- Keep classes focused on a single responsibility.
+
+### Bulkification
+- All methods must operate on collections (`List`, `Set`, `Map`) by default.
+- Never accept a single SObject when a `List<SObject>` is appropriate.
+- Provide convenience overloads for single-record callers only when it makes the API cleaner, and have them delegate to the bulk method.
+
+### Governor Limit Safety
+- **No SOQL or DML inside loops.** Ever.
+- Collect IDs/records first, query/DML once outside the loop.
+- Use `Limits` class checks in batch/bulk operations where appropriate.
+- Prefer `Database.insert(records, false)` with error handling in batch contexts.
+
+### Sharing Model
+- Default to `with sharing` unless the user specifies otherwise.
+- If `without sharing` or `inherited sharing` is used, add an ApexDoc `@description` comment explaining WHY.
+
+### Naming Conventions
+
+| Class Type   | Pattern                        | Example                        |
+|-------------|-------------------------------|-------------------------------|
+| Service      | `{SObject}Service`            | `AccountService`              |
+| Selector     | `{SObject}Selector`           | `AccountSelector`             |
+| Domain       | `{SObject}Domain`             | `OpportunityDomain`           |
+| Batch        | `{Descriptive}Batch`          | `AccountDeduplicationBatch`   |
+| Queueable    | `{Descriptive}Queueable`      | `ExternalSyncQueueable`       |
+| Schedulable  | `{Descriptive}Schedulable`    | `DailyCleanupSchedulable`     |
+| DTO          | `{Descriptive}DTO`            | `AccountMergeRequestDTO`      |
+| Wrapper      | `{Descriptive}Wrapper`        | `OpportunityLineWrapper`      |
+| Utility      | `{Descriptive}Util`           | `StringUtil`, `DateUtil`      |
+| Interface    | `I{Descriptive}`              | `INotificationService`        |
+| Abstract     | `Abstract{Descriptive}`       | `AbstractIntegrationService`  |
+| Exception    | `{Descriptive}Exception`      | `AccountServiceException`     |
+
+### ApexDoc Comments
+Include ApexDoc on every `public` and `global` method and on the class itself:
+
+```apex
+/**
+ * @description Brief description of what the class does
+ * @author Generated by Apex Class Writer Skill
+ */
+```
+
+```apex
+/**
+ * @description Brief description of what the method does
+ * @param paramName Description of the parameter
+ * @return Description of the return value
+ * @example
+ * List<Account> results = AccountService.deduplicateAccounts(accountIds);
+ */
+```
+
+### Null Safety
+- Use guard clauses at the top of methods for null/empty inputs.
+- Use safe navigation (`?.`) where appropriate.
+- Return empty collections rather than `null`.
+
+### Constants
+- No magic strings or numbers in logic.
+- Use `private static final` constants or a dedicated constants class.
+- Use `Label.` custom labels for user-facing strings when appropriate.
+
+### Custom Exceptions
+- Each service class should define or reference a corresponding custom exception.
+- Inner exception classes are preferred for simple cases: `public class AccountServiceException extends Exception {}`
+- Include meaningful error messages with context.
+
+### Error Handling
+- Catch specific exceptions, not generic `Exception` unless re-throwing.
+- Log errors meaningfully (assume a logging utility exists or stub one).
+- In batch contexts, use `Database.SaveResult` / `Database.UpsertResult` with partial success.
+
+---
+
+## Output Format
+
+For every class, produce TWO files:
+
+1. **`{ClassName}.cls`** — The Apex class source code
+2. **`{ClassName}.cls-meta.xml`** — The metadata file
+
+### Meta XML Template
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<ApexClass xmlns="http://soap.sforce.com/2006/04/metadata">
+    <apiVersion>{API_VERSION}</apiVersion>
+    <status>Active</status>
+</ApexClass>
+```
+
+Default `apiVersion` is `62.0` unless the user specifies otherwise.
+
+---
+
+## Class Type–Specific Instructions
+
+### Service Classes
+- Read and follow: `assets/service.cls`
+- Stateless — no instance variables holding mutable state
+- All public methods should be `static` unless there's a compelling reason for instance methods
+- Delegate queries to a Selector class
+- Wrap business logic errors in a custom exception
+
+### Selector Classes
+- Read and follow: `assets/selector.cls`
+- One Selector per SObject (or per logical query domain)
+- Return `List<SObject>` or `Map<Id, SObject>`
+- Accept filter criteria as method parameters, not hardcoded
+- Include a private method that returns the base field list to keep DRY
+
+### Domain Classes
+- Read and follow: `assets/domain.cls`
+- Encapsulate field-level defaults, derivations, and validations
+- Operate on `List<SObject>` — designed to be called from triggers or services
+- No SOQL or DML — only in-memory SObject manipulation
+
+### Batch Classes
+- Read and follow: `assets/batch.cls`
+- Implement `Database.Batchable<SObject>` and optionally `Database.Stateful`
+- Use `Database.QueryLocator` in `start()` for large datasets
+- Handle partial failures in `execute()` using `Database.SaveResult`
+- Implement meaningful `finish()` — at minimum, log completion
+
+### Queueable Classes
+- Read and follow: `assets/queueable.cls`
+- Implement `Queueable` and optionally `Database.AllowsCallouts`
+- Accept data through the constructor — queueables are stateful
+- For chaining, include guard logic to prevent infinite chains
+- Optionally implement `Finalizer` for error recovery
+
+### Schedulable Classes
+- Read and follow: `assets/schedulable.cls`
+- Implement `Schedulable`
+- Keep `execute()` lightweight — delegate to a Batch or Queueable
+- Include a static method that returns a CRON expression for convenience
+- Document the expected schedule in ApexDoc
+
+### DTO / Wrapper Classes
+- Read and follow: `assets/dto.cls`
+- Use `public` properties — no getters/setters unless validation is needed
+- Include a no-arg constructor and optionally a parameterized constructor
+- Implement `Comparable` if sorting is needed
+- Keep them serialization-friendly (no transient state unless intentional)
+
+### Utility Classes
+- Read and follow: `assets/utility.cls`
+- All methods `public static`
+- Class should be `public with sharing` with a `private` constructor to prevent instantiation
+- Group related utilities (e.g., `StringUtil`, `DateUtil`, `CollectionUtil`)
+- Every method must be side-effect-free (no DML, no SOQL)
+
+### Interfaces
+- Read and follow: `assets/interface.cls`
+- Define the contract clearly with ApexDoc on every method signature
+- Use meaningful names that describe the capability: `INotificationService`, `IRetryable`
+
+### Abstract Classes
+- Read and follow: `assets/abstract.cls`
+- Provide default implementations for common behavior
+- Mark extension points as `protected virtual` or `protected abstract`
+- Include a concrete example in the ApexDoc showing how to extend
+
+### Custom Exceptions
+- Read and follow: `assets/exception.cls`
+- Extend `Exception`
+- Keep them simple — Apex exceptions don't support custom constructors well
+- Name them descriptively: `AccountServiceException`, `IntegrationTimeoutException`
+
+---
+
+## Generation Workflow
+
+1. Determine the class type from the user's request
+2. Read the corresponding template from `assets/`
+3. Read relevant examples from `references/` if the class type has one
+4. Apply the user's requirements to the template pattern
+5. Generate the `.cls` file with full ApexDoc
+6. Generate the `.cls-meta.xml` file
+7. Present both files to the user
+8. Include a brief note on design decisions if any non-obvious choices were made
+
+---
+
+## Anti-Patterns to Avoid
+
+- ❌ SOQL or DML inside loops
+- ❌ Hardcoded IDs or record type names (use `Schema.SObjectType` or Custom Metadata)
+- ❌ God classes that mix query + logic + DML
+- ❌ `public` fields on service classes
+- ❌ Returning `null` from methods that should return collections
+- ❌ Generic `catch (Exception e)` without re-throwing or meaningful handling
+- ❌ Business logic in Batch `start()` methods
+- ❌ Tight coupling between classes — use interfaces for extensibility
+- ❌ Magic strings or numbers
+- ❌ Methods longer than ~40 lines — break them into private helpers

package/skills/generating-apex/assets/abstract.cls

@@ -0,0 +1,128 @@
+/**
+ * @description Abstract base class for {describe the family of classes this serves}.
+ *              Provides common behavior and defines extension points for subclasses.
+ *              Subclasses must implement the abstract methods to provide specific behavior.
+ * @author Generated by Apex Class Writer Skill
+ *
+ * @example
+ * // Extending this abstract class:
+ * public class SalesforceIntegrationService extends {ClassName} {
+ *     protected override String getEndpoint() {
+ *         return 'callout:Salesforce_API/services/data/v62.0';
+ *     }
+ *
+ *     protected override Map<String, String> getHeaders() {
+ *         return new Map<String, String>{
+ *             'Content-Type' => 'application/json'
+ *         };
+ *     }
+ * }
+ */
+public abstract with sharing class {ClassName} {
+
+    // ─── Constants ───────────────────────────────────────────────────────
+    private static final Integer DEFAULT_TIMEOUT_MS = 30000;
+
+    // ─── Protected State ─────────────────────────────────────────────────
+    protected Integer timeoutMs;
+
+    // ─── Constructor ─────────────────────────────────────────────────────
+
+    /**
+     * @description Initializes the base class with default configuration
+     */
+    protected {ClassName}() {
+        this.timeoutMs = DEFAULT_TIMEOUT_MS;
+    }
+
+    // ─── Abstract Methods (must be implemented by subclasses) ────────────
+
+    /**
+     * @description Returns the endpoint URL for this integration.
+     *              Subclasses must provide their specific endpoint.
+     * @return The endpoint URL as a String
+     */
+    protected abstract String getEndpoint();
+
+    /**
+     * @description Returns the HTTP headers for this integration.
+     *              Subclasses define their own required headers.
+     * @return Map of header name to header value
+     */
+    protected abstract Map<String, String> getHeaders();
+
+    // ─── Virtual Methods (can be overridden by subclasses) ───────────────
+
+    /**
+     * @description Hook called before the main operation executes.
+     *              Override to add pre-processing logic.
+     *              Default implementation does nothing.
+     * @param context Map of contextual data
+     */
+    protected virtual void beforeExecute(Map<String, Object> context) {
+        // Default: no-op — override in subclass if needed
+    }
+
+    /**
+     * @description Hook called after the main operation completes.
+     *              Override to add post-processing logic.
+     *              Default implementation does nothing.
+     * @param context Map of contextual data
+     * @param result The result from the operation
+     */
+    protected virtual void afterExecute(Map<String, Object> context, Object result) {
+        // Default: no-op — override in subclass if needed
+    }
+
+    // ─── Template Method (common workflow) ───────────────────────────────
+
+    /**
+     * @description Executes the operation using the template method pattern.
+     *              Calls beforeExecute → doExecute → afterExecute in sequence.
+     * @param context Map of data needed for the operation
+     * @return The result of the operation
+     */
+    public Object execute(Map<String, Object> context) {
+        beforeExecute(context);
+
+        Object result;
+        try {
+            result = doExecute(context);
+        } catch (Exception e) {
+            handleError(e);
+            throw e;
+        }
+
+        afterExecute(context, result);
+        return result;
+    }
+
+    // ─── Protected Helpers ───────────────────────────────────────────────
+
+    /**
+     * @description Core execution logic — override this for the main operation.
+     *              Default implementation throws — subclass must provide implementation.
+     * @param context Map of data needed for the operation
+     * @return The result of the operation
+     */
+    protected virtual Object doExecute(Map<String, Object> context) {
+        throw new UnsupportedOperationException(
+            'Subclass must override doExecute()'
+        );
+    }
+
+    /**
+     * @description Error handler called when doExecute throws.
+     *              Override to customize error handling (e.g., logging, retry).
+     * @param e The exception that was thrown
+     */
+    protected virtual void handleError(Exception e) {
+        System.debug(LoggingLevel.ERROR,
+            this.toString() + ' error: ' + e.getMessage() + '\n' + e.getStackTraceString()
+        );
+    }
+
+    // ─── Exception ───────────────────────────────────────────────────────
+
+    public class UnsupportedOperationException extends Exception {}
+}

package/skills/generating-apex/assets/batch.cls

@@ -0,0 +1,125 @@
+/**
+ * @description Batch Apex class for {describe the batch operation}.
+ *              Processes {SObject} records in configurable batch sizes.
+ *              Implements Database.Stateful to track cumulative results across chunks.
+ * @author Generated by Apex Class Writer Skill
+ *
+ * @example
+ * // Execute with default batch size
+ * Database.executeBatch(new {ClassName}());
+ *
+ * // Execute with custom batch size
+ * Database.executeBatch(new {ClassName}(), 100);
+ */
+public with sharing class {ClassName} implements Database.Batchable<SObject>, Database.Stateful {
+
+    // ─── Constants ───────────────────────────────────────────────────────
+    private static final Integer DEFAULT_BATCH_SIZE = 200;
+
+    // ─── Stateful Tracking ───────────────────────────────────────────────
+    private Integer totalProcessed = 0;
+    private Integer totalErrors = 0;
+    private List<String> errorMessages = new List<String>();
+
+    // ─── Constructor ─────────────────────────────────────────────────────
+
+    /**
+     * @description Default constructor
+     */
+    public {ClassName}() {
+        // Default configuration
+    }
+
+    // ─── Batchable Interface ─────────────────────────────────────────────
+
+    /**
+     * @description Defines the scope of records to process.
+     *              Uses Database.QueryLocator for efficient large-dataset processing.
+     * @param bc The batch context
+     * @return QueryLocator for the records to process
+     */
+    public Database.QueryLocator start(Database.BatchableContext bc) {
+        return Database.getQueryLocator([
+            SELECT Id, Name
+            // TODO: Add fields needed for processing
+            FROM {SObject}
+            // TODO: Add WHERE clause to scope the records
+        ]);
+    }
+
+    /**
+     * @description Processes each batch of records.
+     *              Uses Database.update with allOrNone=false for partial success handling.
+     * @param bc The batch context
+     * @param scope List of {SObject} records in the current batch
+     */
+    public void execute(Database.BatchableContext bc, List<{SObject}> scope) {
+        List<{SObject}> recordsToUpdate = new List<{SObject}>();
+
+        for ({SObject} record : scope) {
+            // TODO: Apply business logic to each record
+            recordsToUpdate.add(record);
+        }
+
+        if (!recordsToUpdate.isEmpty()) {
+            List<Database.SaveResult> results = Database.update(recordsToUpdate, false);
+            processResults(results);
+        }
+    }
+
+    /**
+     * @description Performs post-processing after all batches complete.
+     *              Logs a summary of the batch execution.
+     * @param bc The batch context
+     */
+    public void finish(Database.BatchableContext bc) {
+        String summary = String.format(
+            '{0} completed. Processed: {1}, Errors: {2}',
+            new List<Object>{
+                {ClassName}.class.getName(),
+                totalProcessed,
+                totalErrors
+            }
+        );
+
+        System.debug(LoggingLevel.INFO, summary);
+
+        if (!errorMessages.isEmpty()) {
+            System.debug(LoggingLevel.ERROR, 'Error details: ' + String.join(errorMessages, '\n'));
+        }
+
+        // TODO: Send completion notification email or post to chatter if needed
+    }
+
+    // ─── Private Helpers ─────────────────────────────────────────────────
+
+    /**
+     * @description Processes Database.SaveResult list, tracking successes and failures
+     * @param results List of SaveResult from a DML operation
+     */
+    private void processResults(List<Database.SaveResult> results) {
+        for (Database.SaveResult result : results) {
+            if (result.isSuccess()) {
+                totalProcessed++;
+            } else {
+                totalErrors++;
+                for (Database.Error err : result.getErrors()) {
+                    errorMessages.add(
+                        'Record ' + result.getId() + ': ' +
+                        err.getStatusCode() + ' - ' + err.getMessage()
+                    );
+                }
+            }
+        }
+    }
+
+    // ─── Static Helpers ──────────────────────────────────────────────────
+
+    /**
+     * @description Convenience method to execute with default batch size
+     * @return The batch job Id
+     */
+    public static Id run() {
+        return Database.executeBatch(new {ClassName}(), DEFAULT_BATCH_SIZE);
+    }
+}

package/skills/generating-apex/assets/domain.cls

@@ -0,0 +1,102 @@
+/**
+ * @description Domain class for {SObject}.
+ *              Encapsulates field-level defaults, derivations, and validations.
+ *              Operates only on in-memory SObject data — no SOQL or DML.
+ * @author Generated by Apex Class Writer Skill
+ */
+public with sharing class {SObject}Domain {
+
+    // ─── Constants ───────────────────────────────────────────────────────
+    // TODO: Add constants for default values, statuses, etc.
+
+    // ─── Field Defaults ──────────────────────────────────────────────────
+
+    /**
+     * @description Applies default field values to new {SObject} records.
+     *              Call this before insert to ensure consistent defaults.
+     * @param records List of {SObject} records to apply defaults to
+     */
+    public static void applyDefaults(List<{SObject}> records) {
+        if (records == null || records.isEmpty()) {
+            return;
+        }
+
+        for ({SObject} record : records) {
+            // TODO: Set default field values
+            // Example:
+            // if (record.Status__c == null) {
+            //     record.Status__c = DEFAULT_STATUS;
+            // }
+        }
+    }
+
+    // ─── Derivations ────────────────────────────────────────────────────
+
+    /**
+     * @description Derives calculated field values based on other fields.
+     *              Call this before insert and before update.
+     * @param records List of {SObject} records to derive values for
+     */
+    public static void deriveFields(List<{SObject}> records) {
+        if (records == null || records.isEmpty()) {
+            return;
+        }
+
+        for ({SObject} record : records) {
+            // TODO: Derive calculated field values
+            // Example:
+            // record.FullAddress__c = buildFullAddress(record);
+        }
+    }
+
+    // ─── Validations ────────────────────────────────────────────────────
+
+    /**
+     * @description Validates {SObject} records and adds errors for any violations.
+     *              Call this before insert and before update.
+     * @param records List of {SObject} records to validate
+     */
+    public static void validate(List<{SObject}> records) {
+        if (records == null || records.isEmpty()) {
+            return;
+        }
+
+        for ({SObject} record : records) {
+            // TODO: Add validation rules
+            // Example:
+            // if (String.isBlank(record.Name)) {
+            //     record.addError('Name is required.');
+            // }
+        }
+    }
+
+    // ─── Comparisons ────────────────────────────────────────────────────
+
+    /**
+     * @description Determines which fields have changed between old and new record versions.
+     *              Useful in before update context.
+     * @param oldRecord The previous version of the record
+     * @param newRecord The current version of the record
+     * @return Set of field API names that have changed
+     */
+    public static Set<String> getChangedFields({SObject} oldRecord, {SObject} newRecord) {
+        Set<String> changedFields = new Set<String>();
+
+        if (oldRecord == null || newRecord == null) {
+            return changedFields;
+        }
+
+        Map<String, Schema.SObjectField> fieldMap = Schema.SObjectType.{SObject}.fields.getMap();
+        for (String fieldName : fieldMap.keySet()) {
+            if (oldRecord.get(fieldName) != newRecord.get(fieldName)) {
+                changedFields.add(fieldName);
+            }
+        }
+
+        return changedFields;
+    }
+
+    // ─── Private Helpers ─────────────────────────────────────────────────
+
+    // TODO: Add private helper methods as needed
+}