scc-universal 1.1.0

package/.cursor/skills/sf-trigger-frameworks/SKILL.md

@@ -0,0 +1,343 @@
+---
+name: sf-trigger-frameworks
+description: >-
+  Salesforce Apex trigger framework patterns — TriggerHandler, FFLIB Domain, TDTM, bypass and recursion control. Use when adopting or refactoring triggers.
+disable-model-invocation: true
+---
+
+# Trigger Frameworks
+
+Implementation guidance for trigger framework patterns. Constraint rules (one-trigger-per-object, no-logic-in-trigger-body, etc.) live in `sf-trigger-constraints`. This skill covers the _how_ — framework selection, base class implementation, bypass mechanisms, and recursion prevention.
+
+Reference: @../_reference/TRIGGER_PATTERNS.md
+
+---
+
+## When to Use
+
+- When evaluating which trigger framework pattern to adopt for a new project
+- When refactoring bare trigger logic to a handler-based architecture
+- When a trigger is firing recursively and causing unexpected DML or loop errors
+- When you need a bypass mechanism to suppress triggers during data migrations
+- When multiple triggers exist on the same SObject and need to be consolidated
+- When comparing Pragmatic TriggerHandler vs FFLIB Domain Layer
+
+---
+
+## The Pragmatic TriggerHandler Pattern
+
+A clean, dependency-free framework. The base class provides context-aware routing, bypass mechanism, and recursion control.
+
+### TriggerHandler Base Class
+
+```apex
+public virtual class TriggerHandler {
+
+    // Bypass Registry
+    private static Set<String> bypassedHandlers = new Set<String>();
+
+    // Recursion Control
+    private static Map<String, Integer> depthMap = new Map<String, Integer>();
+    private static final Integer MAX_DEPTH = 2;
+
+    // Context Properties
+    @TestVisible protected Boolean isBefore   { get { return Trigger.isBefore; } }
+    @TestVisible protected Boolean isAfter    { get { return Trigger.isAfter; } }
+    @TestVisible protected Boolean isInsert   { get { return Trigger.isInsert; } }
+    @TestVisible protected Boolean isUpdate   { get { return Trigger.isUpdate; } }
+    @TestVisible protected Boolean isDelete   { get { return Trigger.isDelete; } }
+    @TestVisible protected Boolean isUndelete { get { return Trigger.isUndelete; } }
+
+    protected List<SObject>    newList { get { return Trigger.new; } }
+    protected Map<Id, SObject> newMap  { get { return Trigger.newMap; } }
+    protected List<SObject>    oldList { get { return Trigger.old; } }
+    protected Map<Id, SObject> oldMap  { get { return Trigger.oldMap; } }
+
+    public void run() {
+        String handlerName = getHandlerName();
+        if (isBypassed(handlerName)) return;
+        if (exceedsMaxDepth(handlerName)) return;
+
+        incrementDepth(handlerName);
+        try { dispatch(); }
+        finally { decrementDepth(handlerName); }
+    }
+
+    private void dispatch() {
+        if (isBefore) {
+            if (isInsert) onBeforeInsert();
+            if (isUpdate) onBeforeUpdate();
+            if (isDelete) onBeforeDelete();
+        } else if (isAfter) {
+            if (isInsert)   onAfterInsert();
+            if (isUpdate)   onAfterUpdate();
+            if (isDelete)   onAfterDelete();
+            if (isUndelete) onAfterUndelete();
+        }
+    }
+
+    // Virtual Methods — Override in Concrete Handlers
+    @TestVisible protected virtual void onBeforeInsert()   {}
+    @TestVisible protected virtual void onBeforeUpdate()   {}
+    @TestVisible protected virtual void onBeforeDelete()   {}
+    @TestVisible protected virtual void onAfterInsert()    {}
+    @TestVisible protected virtual void onAfterUpdate()    {}
+    @TestVisible protected virtual void onAfterDelete()    {}
+    @TestVisible protected virtual void onAfterUndelete()  {}
+
+    // Bypass API
+    public static void bypass(String handlerName)       { bypassedHandlers.add(handlerName); }
+    public static void clearBypass(String handlerName)  { bypassedHandlers.remove(handlerName); }
+    public static void clearAllBypasses()               { bypassedHandlers.clear(); }
+    public static Boolean isBypassed(String handlerName) { return bypassedHandlers.contains(handlerName); }
+
+    // Private Helpers
+    private String getHandlerName() { return String.valueOf(this).split(':')[0]; }
+    private Boolean exceedsMaxDepth(String h) { return getDepth(h) >= MAX_DEPTH; }
+    private Integer getDepth(String h) { return depthMap.containsKey(h) ? depthMap.get(h) : 0; }
+    private void incrementDepth(String h) { depthMap.put(h, getDepth(h) + 1); }
+    private void decrementDepth(String h) { Integer c = getDepth(h); if (c > 0) depthMap.put(h, c - 1); }
+}
+```
+
+### Concrete Handler
+
+```apex
+public class AccountTriggerHandler extends TriggerHandler {
+
+    private List<Account>    newAccounts;
+    private Map<Id, Account> oldAccountMap;
+
+    public AccountTriggerHandler() {
+        newAccounts   = (List<Account>) newList;
+        oldAccountMap = (Map<Id, Account>) oldMap;
+    }
+
+    override protected void onBeforeInsert() {
+        AccountDefaults.setDefaults(newAccounts);
+        AccountValidator.validateForInsert(newAccounts);
+    }
+
+    override protected void onBeforeUpdate() {
+        AccountValidator.validateForUpdate(newAccounts, oldAccountMap);
+    }
+
+    override protected void onAfterInsert() {
+        AccountOpportunityCreator.createDefaultOpportunities(newAccounts);
+    }
+
+    override protected void onAfterUpdate() {
+        AccountRelatedUpdater.syncContactOwnership(
+            (Map<Id, Account>) newMap, oldAccountMap
+        );
+    }
+}
+```
+
+### Trigger File
+
+```apex
+trigger AccountTrigger on Account (
+    before insert, before update, before delete,
+    after insert, after update, after delete, after undelete
+) {
+    new AccountTriggerHandler().run();
+}
+```
+
+---
+
+## FFLIB Domain Layer
+
+For orgs using the FFLIB Apex Commons library, the Domain layer is the preferred trigger handling mechanism.
+
+```apex
+public with sharing class Accounts extends fflib_SObjectDomain {
+
+    public Accounts(List<Account> sObjectList) {
+        super(sObjectList);
+        Configuration.disableTriggerCRUDSecurity();
+    }
+
+    public override void onBeforeInsert() {
+        setDefaultCustomerTier();
+    }
+
+    public override void onBeforeUpdate(Map<Id, SObject> existingRecords) {
+        preventPremiumTierDowngrade((Map<Id, Account>) existingRecords);
+    }
+
+    public class Constructor implements fflib_SObjectDomain.IConstructable {
+        public fflib_SObjectDomain construct(List<SObject> sObjectList) {
+            return new Accounts(sObjectList);
+        }
+    }
+}
+```
+
+> `Configuration.disableTriggerCRUDSecurity()` is needed because trigger handlers operate on records already committed by the platform. Do NOT disable CRUD security in Service or Controller layers.
+
+---
+
+## TDTM (Table-Driven Trigger Management)
+
+Registers handlers in Custom Metadata (`Trigger_Handler__mdt`), enabling enable/disable without code deployment.
+
+**CMDT fields:** `Object_Name__c`, `Handler_Class__c`, `Trigger_Event__c`, `Is_Active__c`, `Execution_Order__c`
+
+```apex
+public class TDTMDispatcher {
+
+    private static Map<String, List<Trigger_Handler__mdt>> handlerCache =
+        new Map<String, List<Trigger_Handler__mdt>>();
+
+    public static void run(
+        String objectName, String triggerEvent,
+        List<SObject> newList, List<SObject> oldList,
+        Map<Id, SObject> newMap, Map<Id, SObject> oldMap
+    ) {
+        String cacheKey = objectName + ':' + triggerEvent;
+        List<Trigger_Handler__mdt> activeHandlers;
+        if (handlerCache.containsKey(cacheKey)) {
+            activeHandlers = handlerCache.get(cacheKey);
+        } else {
+            activeHandlers = [
+                SELECT Handler_Class__c, Execution_Order__c
+                FROM Trigger_Handler__mdt
+                WHERE Object_Name__c = :objectName
+                  AND Trigger_Event__c = :triggerEvent
+                  AND Is_Active__c = true
+                ORDER BY Execution_Order__c ASC
+            ];
+            handlerCache.put(cacheKey, activeHandlers);
+        }
+
+        for (Trigger_Handler__mdt cfg : activeHandlers) {
+            Type handlerType = Type.forName(cfg.Handler_Class__c);
+            if (handlerType == null) continue;
+            ITriggerHandler handler = (ITriggerHandler) handlerType.newInstance();
+            handler.execute(newList, oldList, newMap, oldMap);
+        }
+    }
+
+    public interface ITriggerHandler {
+        void execute(List<SObject> newList, List<SObject> oldList,
+                     Map<Id, SObject> newMap, Map<Id, SObject> oldMap);
+    }
+}
+```
+
+To disable a handler for data migration: set `Is_Active__c = false` in Setup.
+
+---
+
+## Bypass Mechanisms
+
+### Static Boolean (Simple)
+
+```apex
+public class TriggerBypasses {
+    public static Boolean bypassAccountTrigger = false;
+}
+
+// Usage
+TriggerBypasses.bypassAccountTrigger = true;
+try {
+    insert accountsToMigrate;
+} finally {
+    TriggerBypasses.bypassAccountTrigger = false;
+}
+```
+
+### Framework-Level (`TriggerHandler.bypass()`)
+
+```apex
+TriggerHandler.bypass('AccountTriggerHandler');
+try {
+    insert accounts;
+} finally {
+    TriggerHandler.clearBypass('AccountTriggerHandler');
+}
+```
+
+### Custom Metadata Bypass (Declarative)
+
+Map users/profiles to bypassed handlers via `Trigger_Bypass__mdt`. No code change needed.
+
+---
+
+## Recursion Prevention
+
+### Static Set of Processed IDs
+
+```apex
+public class AccountTriggerHandler extends TriggerHandler {
+
+    @TestVisible
+    private static Set<Id> processedIds = new Set<Id>();
+
+    override protected void onAfterUpdate() {
+        List<Account> unprocessed = new List<Account>();
+        for (Account acc : (List<Account>) newList) {
+            if (!processedIds.contains(acc.Id)) {
+                processedIds.add(acc.Id);
+                unprocessed.add(acc);
+            }
+        }
+        if (!unprocessed.isEmpty()) {
+            AccountRelatedUpdater.syncContactOwnership(
+                new Map<Id, Account>(unprocessed), (Map<Id, Account>) oldMap
+            );
+        }
+    }
+}
+```
+
+> **Testing note:** Static variables reset between test methods. Within a single test method, they persist across multiple trigger executions.
+
+### Execution Depth Counter
+
+Built into the TriggerHandler base class (MAX_DEPTH = 2). When a handler is called more than MAX_DEPTH times, execution is skipped. This prevents infinite recursion while allowing the first re-entry.
+
+---
+
+## Migration Guide: Bare Trigger to Framework
+
+1. Deploy `TriggerHandler.cls` base class
+2. Create handler class: `public class AccountTriggerHandler extends TriggerHandler {}`
+3. Refactor trigger: replace body with `new AccountTriggerHandler().run();`
+4. Move logic method by method into handler overrides or service classes
+5. Add bypass support via base class or Custom Metadata
+6. Delete old trigger files after consolidation
+
+---
+
+## Testing Trigger Frameworks
+
+```apex
+@isTest
+static void testBypassMechanism_noDefaultsSetWhenBypassed() {
+    TriggerHandler.bypass('AccountTriggerHandler');
+    Account acc = new Account(Name = 'Bypass Test', Type = 'Customer', Industry = 'Tech');
+
+    Test.startTest();
+    insert acc;
+    Test.stopTest();
+
+    TriggerHandler.clearBypass('AccountTriggerHandler');
+
+    Account result = [SELECT Customer_Tier__c FROM Account WHERE Id = :acc.Id];
+    System.assertEquals(null, result.Customer_Tier__c,
+        'Tier should NOT be set when handler is bypassed');
+}
+```
+
+---
+
+## Related
+
+- **Agent**: `sf-architect` — For interactive, in-depth guidance
+
+### Guardrails
+
+- `sf-trigger-constraints` — Enforces one-trigger-per-object, handler delegation, bulkification, and recursion prevention rules

package/.cursor/skills/sf-visualforce-development/SKILL.md

@@ -0,0 +1,259 @@
+---
+name: sf-visualforce-development
+description: >-
+  Visualforce development — pages, controllers, extensions, ViewState, JS Remoting, LWC migration. Use when maintaining VF pages, building PDFs, or planning VF-to-LWC migration. Do NOT use for LWC, Aura, or Flow.
+---
+
+# Visualforce Development
+
+Visualforce is Salesforce's server-side rendering framework. While LWC is the modern standard, Visualforce remains heavily used for PDF generation, email templates, custom overrides, and legacy applications.
+
+## When to Use
+
+- When maintaining or extending existing Visualforce pages in production
+- When building PDF renderable pages (`renderAs="pdf"`) — LWC cannot do this
+- When creating custom email templates with complex formatting
+- When overriding standard buttons (New, Edit, View) with custom UIs
+- When planning and executing migration from Visualforce to LWC
+- When debugging ViewState issues or page performance problems
+
+@../_reference/VISUALFORCE_PATTERNS.md
+
+---
+
+## Page Creation Procedure
+
+### Step 1 — Choose Controller Type
+
+| Type | When to Use |
+|------|------------|
+| Standard Controller | Single-record CRUD without custom logic |
+| Standard List Controller | List views with built-in pagination |
+| Custom Controller | Full control over logic, data, navigation |
+| Controller Extension | Add functionality to standard/custom controllers |
+
+### Step 2 — Create the Page
+
+```html
+<apex:page standardController="Account"
+           extensions="AccountOverviewExtension"
+           lightningStylesheets="true"
+           docType="html-5.0"
+           title="Account Overview">
+    <apex:pageBlock title="Account Details">
+        <apex:pageBlockSection columns="2">
+            <apex:outputField value="{!Account.Name}" />
+            <apex:outputField value="{!Account.Industry}" />
+        </apex:pageBlockSection>
+    </apex:pageBlock>
+</apex:page>
+```
+
+### Step 3 — Custom Controller (if needed)
+
+```apex
+public with sharing class InvoiceController {
+    public List<Invoice__c> invoices { get; private set; }
+    public String searchTerm { get; set; }
+
+    public InvoiceController() {
+        searchTerm = '';
+        loadInvoices();
+    }
+
+    public PageReference search() {
+        loadInvoices();
+        return null; // Stay on same page
+    }
+
+    private void loadInvoices() {
+        String likeSearch = '%' + String.escapeSingleQuotes(searchTerm) + '%';
+        invoices = [
+            SELECT Id, Name, Amount__c, Status__c, CreatedDate
+            FROM Invoice__c WHERE Name LIKE :likeSearch
+            WITH USER_MODE ORDER BY CreatedDate DESC LIMIT 100
+        ];
+    }
+}
+```
+
+### Step 4 — Controller Extension (if needed)
+
+```apex
+public with sharing class AccountOverviewExtension {
+    private final Account account;
+
+    // Required constructor signature
+    public AccountOverviewExtension(ApexPages.StandardController stdController) {
+        if (!Test.isRunningTest()) {
+            stdController.addFields(new List<String>{ 'OwnerId', 'AnnualRevenue' });
+        }
+        this.account = (Account) stdController.getRecord();
+    }
+
+    public List<Contact> relatedContacts {
+        get {
+            if (relatedContacts == null) {
+                relatedContacts = [
+                    SELECT Id, Name, Email, Phone
+                    FROM Contact WHERE AccountId = :account.Id
+                    WITH USER_MODE ORDER BY Name LIMIT 50
+                ];
+            }
+            return relatedContacts;
+        }
+        private set;
+    }
+}
+```
+
+---
+
+## ViewState Management
+
+ViewState is a hidden, encrypted form field that maintains page state across postbacks. **170KB limit** — exceeding it causes a runtime error.
+
+### The `transient` Keyword
+
+Mark variables that do not need to survive postbacks as `transient`:
+
+```apex
+public with sharing class ReportController {
+    // IN ViewState — needed across postbacks
+    public String selectedFilter { get; set; }
+    public Integer currentPage { get; set; }
+
+    // NOT in ViewState — recomputed on each request
+    transient public List<AggregateResult> reportData { get; private set; }
+    transient public Blob chartImage { get; private set; }
+}
+```
+
+### Reduction Strategies
+
+| Strategy | Impact |
+|----------|--------|
+| `transient` keyword on large/recomputable variables | High |
+| `apex:outputPanel` + `reRender` (partial refresh) | Medium |
+| Paginate large data sets | High |
+| Use JavaScript Remoting (stateless) | High |
+| Move read-only data outside `apex:form` | Medium |
+
+---
+
+## JavaScript Remoting
+
+Stateless, high-performance Apex calls that bypass ViewState entirely.
+
+### Apex Method
+
+```apex
+@RemoteAction
+public static List<Account> findAccounts(String searchTerm) {
+    String safeTerm = '%' + String.escapeSingleQuotes(searchTerm) + '%';
+    return [
+        SELECT Id, Name, Industry FROM Account
+        WHERE Name LIKE :safeTerm WITH USER_MODE LIMIT 25
+    ];
+}
+```
+
+### JavaScript Invocation
+
+```javascript
+Visualforce.remoting.Manager.invokeAction(
+    '{!$RemoteAction.AccountSearchController.findAccounts}',
+    term,
+    function(result, event) {
+        if (event.status) {
+            renderResults(result);
+        } else {
+            console.error(event.message);
+        }
+    },
+    { escape: true, timeout: 30000 }
+);
+```
+
+Use `{!$RemoteAction.ClassName.methodName}` (namespace-safe). Set `escape: true` to prevent XSS.
+
+---
+
+## Partial Page Refresh
+
+```html
+<apex:actionFunction name="refreshDashboard" action="{!refresh}"
+                     reRender="dashPanel" status="loadingStatus" />
+
+<apex:selectList value="{!selectedRegion}" size="1">
+    <apex:selectOptions value="{!regionOptions}" />
+    <apex:actionSupport event="onchange" action="{!filterByRegion}"
+                        reRender="dashPanel" status="loadingStatus" />
+</apex:selectList>
+
+<apex:actionStatus id="loadingStatus">
+    <apex:facet name="start"><img src="/img/loading.gif" alt="Loading..." /></apex:facet>
+</apex:actionStatus>
+```
+
+---
+
+## Migration to LWC
+
+### Decision Matrix
+
+| Keep Visualforce | Migrate to LWC |
+|-----------------|----------------|
+| PDF generation (`renderAs="pdf"`) | High-traffic pages needing performance |
+| Email templates | New feature development |
+| Complex server-state wizards | Pages using Apex controller only |
+
+### Key VF-to-LWC Mappings
+
+| Visualforce | LWC |
+|------------|-----|
+| `apex:pageBlockTable` | `lightning-datatable` |
+| `apex:commandButton action="{!save}"` | `lightning-button onclick={handleSave}` + imperative Apex |
+| `apex:inputField` | `lightning-input-field` (in `lightning-record-edit-form`) |
+| JavaScript Remoting | `@wire` or imperative Apex import |
+| `apex:actionSupport` | Standard DOM event handlers |
+| `{!property}` merge fields | `{property}` template expressions |
+
+### Embedding LWC in Visualforce (Lightning Out)
+
+For incremental migration, embed LWC inside existing VF pages:
+
+```html
+<apex:includeLightning />
+<div id="lwc-container"></div>
+<script>
+$Lightning.use("c:lwcOutApp", function() {
+    $Lightning.createComponent("c:accountDashboard",
+        { recordId: "{!Account.Id}" }, "lwc-container");
+});
+</script>
+```
+
+### Migration Checklist
+
+1. **Inventory** — list all VF pages, controllers, usage frequency
+2. **Categorize** — mark each page as Keep VF / Migrate / Retire
+3. **Dependencies** — map controller extensions, custom components, static resources
+4. **Security audit** — review XSS/injection issues before or during migration
+5. **Feature parity** — replicate all VF functionality in LWC
+6. **Test coverage** — write LWC Jest tests to match existing Apex test coverage
+7. **Incremental rollout** — use Lightning Out to embed LWC in VF during transition
+8. **Redirect** — update links, overrides, navigation to new LWC pages
+9. **Deprecate** — mark old VF pages as inactive, remove after validation
+
+---
+
+## Related
+
+### Guardrails
+
+- **sf-security-constraints** — Enforced rules for XSS prevention, SOQL injection, CRUD/FLS enforcement
+
+### Agents
+
+- **sf-visualforce-reviewer** — For interactive, in-depth Visualforce review guidance