scc-universal 1.1.0

package/skills/sf-apex-cursor/SKILL.md

@@ -0,0 +1,338 @@
+---
+name: sf-apex-cursor
+description: "Apex Cursor API for paginating large SOQL results (up to 50M records) — cursor navigation, Queueable chaining, LWC pagination. Use when paginating queries or migrating from OFFSET. Do NOT use for small result sets."
+origin: SCC
+user-invocable: false
+allowed-tools: Read, Grep, Glob, Edit, Write, Bash
+---
+
+# Apex Cursor
+
+The `Cursor` class (GA Spring '26) enables efficient pagination through up to 50 million SOQL rows without the 2,000-row OFFSET limit. Use it for large dataset processing that previously required chunked OFFSET patterns or raw Batch Apex.
+
+Reference: @../_reference/APEX_CURSOR.md
+
+---
+
+## When to Use
+
+- When implementing paginated queries over large datasets using the Apex Cursor API
+- When OFFSET-based pagination hits governor limits or performance issues on large result sets
+- When building `@AuraEnabled` methods with server-side cursor pagination for LWC components
+- When migrating legacy OFFSET queries to cursor-based iteration for scalability beyond 2,000 rows
+
+---
+
+## Cursor vs. OFFSET vs. Batch Apex
+
+| Approach | Max Records | Heap Impact | Best For |
+|----------|------------|-------------|----------|
+| SOQL `OFFSET` | 2,000 | Full result set in heap | Small UI pagination |
+| Batch Apex | Unlimited | Per-execute governor reset | Background mass processing |
+| `Cursor` class | 50,000,000 | Per-page only | Large paginated reports, async chaining, LWC infinite scroll |
+
+### Performance Comparison
+
+| Record Count | Best Approach | Why |
+|-------------|--------------|-----|
+| < 200 | Standard SOQL with `LIMIT` | Simple, no overhead |
+| 200 - 2,000 | `OFFSET` pagination | Adequate performance, simpler code |
+| 2,000 - 50,000 | `Cursor` | OFFSET degrades above 2K; Cursor maintains constant performance |
+| 50,000+ | `Cursor` + Queueable chaining | Single cursor handles up to 50M records |
+| Batch processing | `Database.QueryLocator` | Full governor reset per execute chunk |
+
+**Key insight:** OFFSET forces the database to skip N rows on every request. At 10,000 OFFSET, the DB scans and discards 10K rows. Cursor maintains a server-side pointer with no scanning overhead regardless of position.
+
+---
+
+## Cursor Class API
+
+```apex
+// Open a cursor — returns a server-side pointer, not the data
+Database.Cursor cursor = Database.getCursor('SELECT Id, Name FROM Account ORDER BY Id');
+
+// Fetch a page of records starting at offset
+List<SObject> page = cursor.fetch(offset, pageSize);
+
+// Total number of records the cursor can return
+Integer total = cursor.getNumRecords();
+
+// Serialize the cursor for use across transactions (Queueable chaining)
+String cursorId = cursor.getId();
+
+// Re-open a serialized cursor in a new transaction
+Database.Cursor resumed = Database.getCursor(cursorId);
+
+// Always close when done to release server-side resources
+cursor.close();
+```
+
+---
+
+## Basic Cursor Pagination
+
+Process data page-by-page without loading everything into heap. Do not accumulate all rows in memory.
+
+```apex
+public class LargeAccountAuditor {
+
+    public static AuditSummary auditAccounts() {
+        Database.Cursor cursor = Database.getCursor(
+            'SELECT Id, Name, AnnualRevenue, Industry FROM Account ORDER BY Name'
+        );
+
+        Integer pageSize = 2000;
+        Integer offset = 0;
+        Decimal totalRevenue = 0;
+        Integer totalCount = 0;
+        List<Audit_Log__c> logsToInsert = new List<Audit_Log__c>();
+
+        try {
+            while (offset < cursor.getNumRecords()) {
+                List<Account> page = cursor.fetch(offset, pageSize);
+
+                for (Account acc : page) {
+                    totalRevenue += acc.AnnualRevenue != null ? acc.AnnualRevenue : 0;
+                    totalCount++;
+
+                    if (acc.AnnualRevenue == null || acc.AnnualRevenue == 0) {
+                        logsToInsert.add(new Audit_Log__c(
+                            Record_Id__c = acc.Id,
+                            Finding__c   = 'Missing AnnualRevenue'
+                        ));
+                    }
+                }
+                // page goes out of scope — GC-eligible, heap stays flat
+
+                if (logsToInsert.size() >= 5000) {
+                    insert logsToInsert;
+                    logsToInsert.clear();
+                }
+
+                offset += pageSize;
+            }
+
+            if (!logsToInsert.isEmpty()) insert logsToInsert;
+        } finally {
+            cursor.close();
+        }
+
+        return new AuditSummary(totalCount, totalRevenue);
+    }
+}
+```
+
+---
+
+## Async Cursor Chaining with Queueable
+
+Serialize a Cursor by ID and pass it across Queueable jobs to process 50M records across chained async transactions.
+
+```apex
+public class LargeLeadProcessorQueueable implements Queueable {
+
+    private String  cursorId;
+    private Integer offset;
+    private static final Integer PAGE_SIZE = 2000;
+
+    // First call — no cursor yet
+    public LargeLeadProcessorQueueable() {
+        Database.Cursor cursor = Database.getCursor(
+            'SELECT Id, Status, LeadSource FROM Lead WHERE IsConverted = false ORDER BY Id'
+        );
+        this.cursorId = cursor.getId();
+        this.offset   = 0;
+        cursor.close(); // Close handle; cursor remains alive on server
+    }
+
+    // Subsequent calls — resume from cursor
+    public LargeLeadProcessorQueueable(String cursorId, Integer offset) {
+        this.cursorId = cursorId;
+        this.offset   = offset;
+    }
+
+    public void execute(QueueableContext ctx) {
+        Database.Cursor cursor = Database.getCursor(this.cursorId);
+
+        if (this.offset >= cursor.getNumRecords()) {
+            cursor.close();
+            return;
+        }
+
+        List<Lead> page = cursor.fetch(this.offset, PAGE_SIZE);
+        processLeads(page);
+
+        Integer nextOffset = this.offset + page.size();
+
+        if (nextOffset < cursor.getNumRecords()) {
+            cursor.close();
+            System.enqueueJob(new LargeLeadProcessorQueueable(this.cursorId, nextOffset));
+        } else {
+            cursor.close();
+        }
+    }
+}
+```
+
+---
+
+## PaginationCursor for LWC / @AuraEnabled
+
+For user-facing pagination (LWC infinite scroll, Screen Flows), use `Database.PaginationCursor`. It is `@AuraEnabled` compatible.
+
+```apex
+public with sharing class AccountPaginationController {
+
+    private static final Integer DEFAULT_PAGE_SIZE = 20;
+
+    @AuraEnabled(cacheable=false)
+    public static PageResult getAccounts(String cursorId, Integer pageSize) {
+        if (pageSize == null || pageSize <= 0) pageSize = DEFAULT_PAGE_SIZE;
+
+        Database.PaginationCursor cursor;
+        if (String.isBlank(cursorId)) {
+            cursor = Database.getPaginationCursor(
+                'SELECT Id, Name, Industry, AnnualRevenue FROM Account ORDER BY Name'
+            );
+        } else {
+            cursor = Database.getPaginationCursor(cursorId);
+        }
+
+        List<Account> page = cursor.fetch(pageSize);
+
+        PageResult result = new PageResult();
+        result.records    = page;
+        result.cursorId   = cursor.getId();
+        result.hasMore    = cursor.hasMore();
+        result.totalCount = cursor.getNumRecords();
+        return result;
+    }
+
+    public class PageResult {
+        @AuraEnabled public List<Account> records;
+        @AuraEnabled public String cursorId;
+        @AuraEnabled public Boolean hasMore;
+        @AuraEnabled public Integer totalCount;
+    }
+}
+```
+
+### LWC Integration
+
+```javascript
+import { LightningElement } from 'lwc';
+import getAccounts from '@salesforce/apex/AccountPaginationController.getAccounts';
+
+export default class AccountInfiniteList extends LightningElement {
+    accounts = [];
+    cursorId = null;
+    hasMore = true;
+    isLoading = false;
+
+    connectedCallback() { this.loadPage(); }
+
+    async loadPage() {
+        if (this.isLoading || !this.hasMore) return;
+        this.isLoading = true;
+        try {
+            const result = await getAccounts({ cursorId: this.cursorId, pageSize: 20 });
+            this.accounts = [...this.accounts, ...result.records];
+            this.cursorId = result.cursorId;
+            this.hasMore  = result.hasMore;
+        } catch (error) {
+            console.error('Pagination error:', error);
+        } finally {
+            this.isLoading = false;
+        }
+    }
+
+    handleLoadMore() { this.loadPage(); }
+}
+```
+
+---
+
+## Cursor Limits
+
+| Constraint | Detail |
+|-----------|--------|
+| Max records per cursor | 50,000,000 |
+| Cursor lifetime (sync) | 10 minutes |
+| Cursor lifetime (async) | 60 minutes |
+| `fetch()` max page size | 2,000 rows per call |
+| Max open cursors | 10 per transaction |
+| `PaginationCursor` @AuraEnabled | Fully supported |
+
+### Error Handling
+
+Always close cursors in a `try/finally` block.
+
+```apex
+Database.Cursor cursor = Database.getCursor('SELECT Id FROM Lead');
+try {
+    List<Lead> leads = cursor.fetch(0, 100);
+    processLeads(leads);
+} catch (System.CursorException e) {
+    // Cursor expired or already closed
+    System.debug(LoggingLevel.WARN, 'Cursor error: ' + e.getMessage());
+    throw;
+} finally {
+    try { cursor.close(); } catch (Exception ignored) {}
+}
+```
+
+| Error | Cause | Fix |
+|-------|-------|-----|
+| `Cursor has been closed` | `fetch()` after `close()` | Check cursor state before fetching |
+| `Cursor has expired` | > 10 min sync / 60 min async | Process faster or use Queueable chaining |
+| `Maximum cursors exceeded` | > 10 open cursors | Close cursors in `finally` blocks |
+| `Non-selective query` | WHERE clause not indexed | Add custom index or narrow query |
+
+---
+
+## Testing Cursor Code
+
+```apex
+@IsTest
+private class CursorPaginationTest {
+
+    @TestSetup
+    static void makeData() {
+        List<Account> accounts = new List<Account>();
+        for (Integer i = 0; i < 500; i++) {
+            accounts.add(new Account(Name = 'Cursor Test ' + String.valueOf(i).leftPad(3, '0')));
+        }
+        insert accounts;
+    }
+
+    @IsTest
+    static void shouldPaginateThroughAllRecords() {
+        Test.startTest();
+        Database.Cursor cursor = Database.getCursor(
+            'SELECT Id, Name FROM Account WHERE Name LIKE \'Cursor Test%\' ORDER BY Name'
+        );
+        Integer totalFetched = 0;
+        try {
+            while (totalFetched < cursor.getNumRecords()) {
+                List<Account> page = (List<Account>) cursor.fetch(totalFetched, 200);
+                totalFetched += page.size();
+            }
+        } finally {
+            cursor.close();
+        }
+        Test.stopTest();
+        System.assertEquals(500, totalFetched, 'Should fetch all 500 records');
+    }
+}
+```
+
+---
+
+## Related
+
+- **Skills**: `sf-apex-async-patterns` — For Queueable chaining patterns
+
+### Guardrails
+
+- `sf-apex-constraints` — Governs SOQL and DML usage in cursor-processing code
+- `sf-soql-constraints` — Governs query structure and selectivity requirements

package/skills/sf-apex-enterprise-patterns/SKILL.md

@@ -0,0 +1,348 @@
+---
+name: sf-apex-enterprise-patterns
+description: >-
+  Use when implementing Salesforce Apex Enterprise Patterns (FFLIB) — Selector,
+  Domain, Service, Unit of Work layers. Do NOT use for simple orgs or constraints.
+origin: SCC
+user-invocable: false
+allowed-tools: Read, Grep, Glob, Edit, Write, Bash
+---
+
+# Apex Enterprise Patterns
+
+Implementation guidance for Apex Enterprise Patterns (AEP / FFLIB). Covers the four-layer architecture, pragmatic adoption, and when NOT to use them. Constraint rules live in `sf-apex-constraints`.
+
+Reference: @../_reference/ENTERPRISE_PATTERNS.md
+
+---
+
+## When to Use
+
+- When building Apex applications that will scale beyond 5 developers or 50 custom classes
+- When trigger logic is becoming complex and duplicated across multiple contexts
+- When SOQL queries are scattered throughout classes instead of centralized
+- When implementing FFLIB (Andy Fawcett) patterns in a Salesforce project
+- When separating business logic from trigger context to improve testability
+- When a service method needs to coordinate inserts, updates, and deletes atomically
+
+## When NOT to Use
+
+- **Simple automations**: A before-insert trigger that sets a default status
+- **One-off scripts**: Data migration or fix scripts
+- **Small orgs** (< 5 developers, < 50 custom classes)
+- **Read-only visualizations**: A Selector is often sufficient
+
+The rule: introduce a layer when the absence of that layer is causing a real problem.
+
+---
+
+## Architecture Overview
+
+```
+Trigger / Controller / API
+        |
+   Service Layer        <- Transaction boundary, orchestration
+        |
+  Domain Layer          <- Business rules on record collections
+        |
+  Selector Layer        <- All SOQL queries
+        |
+   Unit of Work         <- All DML (atomic commit)
+```
+
+---
+
+## Selector Layer
+
+Selectors own all SOQL queries for an object. No SOQL appears outside a Selector.
+
+**Naming:** `{ObjectNamePlural}Selector` — e.g., `AccountsSelector`, `OpportunitiesSelector`
+
+### Without FFLIB
+
+```apex
+public with sharing class AccountsSelector {
+
+    @TestVisible
+    private static AccountsSelector instance;
+
+    public static AccountsSelector newInstance() {
+        if (instance == null) instance = new AccountsSelector();
+        return instance;
+    }
+
+    public List<Account> selectById(Set<Id> accountIds) {
+        return [
+            SELECT Id, Name, Type, OwnerId, AnnualRevenue,
+                   Customer_Tier__c, CreditLimit__c
+            FROM Account WHERE Id IN :accountIds
+            WITH USER_MODE ORDER BY Name
+        ];
+    }
+
+    public List<Account> selectWithOpenOpportunitiesById(Set<Id> accountIds) {
+        return [
+            SELECT Id, Name, AnnualRevenue, Customer_Tier__c,
+                   (SELECT Id, Name, Amount, CloseDate, StageName
+                    FROM Opportunities WHERE IsClosed = false
+                    ORDER BY CloseDate ASC)
+            FROM Account WHERE Id IN :accountIds WITH USER_MODE
+        ];
+    }
+}
+```
+
+### With FFLIB
+
+```apex
+public with sharing class AccountsSelector extends fflib_SObjectSelector {
+
+    public static AccountsSelector newInstance() {
+        return (AccountsSelector) Application.Selector.newInstance(Account.SObjectType);
+    }
+
+    public Schema.SObjectType getSObjectType() { return Account.SObjectType; }
+
+    public List<Schema.SObjectField> getSObjectFieldList() {
+        return new List<Schema.SObjectField>{
+            Account.Id, Account.Name, Account.Type,
+            Account.OwnerId, Account.AnnualRevenue
+        };
+    }
+
+    public List<Account> selectById(Set<Id> accountIds) {
+        return (List<Account>) selectSObjectsById(accountIds);
+    }
+}
+```
+
+---
+
+## Domain Layer
+
+Encapsulates all business logic for a collection of records of the same type. Replaces trigger logic.
+
+**Naming:** `{ObjectNamePlural}` — e.g., `Accounts`, `Opportunities`
+
+```apex
+public with sharing class Accounts {
+
+    private final List<Account> records;
+    private final Map<Id, Account> existingRecords;
+
+    public static Accounts newInstance(List<Account> records) {
+        return new Accounts(records, null);
+    }
+
+    public static Accounts newInstance(List<Account> records, Map<Id, Account> existing) {
+        return new Accounts(records, existing);
+    }
+
+    private Accounts(List<Account> records, Map<Id, Account> existingRecords) {
+        this.records         = records;
+        this.existingRecords = existingRecords;
+    }
+
+    public void onBeforeInsert() {
+        setDefaultCustomerTier();
+        validateRequiredFields();
+    }
+
+    public void onBeforeUpdate() {
+        validateRequiredFields();
+        preventDowngradingPremiumTier();
+    }
+
+    public void setDefaultCustomerTier() {
+        for (Account acc : records) {
+            if (String.isBlank(acc.Customer_Tier__c)) acc.Customer_Tier__c = 'Standard';
+        }
+    }
+
+    public void validateRequiredFields() {
+        for (Account acc : records) {
+            if (acc.Type == 'Customer' && String.isBlank(acc.Industry)) {
+                acc.Industry.addError('Industry is required for Customer account type.');
+            }
+        }
+    }
+
+    public void preventDowngradingPremiumTier() {
+        for (Account acc : records) {
+            Account existing = existingRecords?.get(acc.Id);
+            if (existing == null) continue;
+            if (existing.Customer_Tier__c == 'Premium'
+                    && acc.Customer_Tier__c != 'Premium') {
+                acc.Customer_Tier__c.addError(
+                    'Premium tier downgrade requires approval.'
+                );
+            }
+        }
+    }
+}
+```
+
+### Trigger Using Domain Layer
+
+```apex
+trigger AccountTrigger on Account (
+    before insert, before update, after insert, after update
+) {
+    if (Trigger.isBefore && Trigger.isInsert) {
+        Accounts.newInstance(Trigger.new).onBeforeInsert();
+    } else if (Trigger.isBefore && Trigger.isUpdate) {
+        Accounts.newInstance(Trigger.new, Trigger.oldMap).onBeforeUpdate();
+    }
+}
+```
+
+---
+
+## Service Layer
+
+Orchestrates business processes that span multiple objects or require a full transaction boundary.
+
+**Naming:** `{ObjectNamePlural}Service` — e.g., `AccountsService`
+
+**Rules:**
+
+1. Static methods only — services are stateless
+2. No SOQL — delegate to Selectors
+3. No direct DML — use Unit of Work
+4. Owns the transaction boundary
+5. Calls Domain methods for record-level rules
+
+```apex
+public with sharing class AccountsService {
+
+    public static void upgradeToPremium(Set<Id> accountIds) {
+        List<Account> accounts = AccountsSelector.newInstance()
+            .selectWithOpenOpportunitiesById(accountIds);
+
+        if (accounts.isEmpty()) {
+            throw new UpgradeException('No accounts found for IDs: ' + accountIds);
+        }
+
+        // Validate
+        List<String> errors = validateForUpgrade(accounts);
+        if (!errors.isEmpty()) {
+            throw new UpgradeException(String.join(errors, '\n'));
+        }
+
+        // Build Unit of Work
+        fflib_ISObjectUnitOfWork uow = Application.UnitOfWork.newInstance();
+        for (Account acc : accounts) {
+            acc.Customer_Tier__c  = 'Premium';
+            acc.CreditLimit__c    = 100000.00;
+            uow.registerDirty(acc);
+
+            uow.registerNew(new Opportunity(
+                Name      = acc.Name + ' - Premium Welcome',
+                AccountId = acc.Id,
+                StageName = 'Qualification',
+                CloseDate = Date.today().addDays(30)
+            ));
+        }
+
+        uow.commitWork(); // One atomic DML transaction
+    }
+
+    public class UpgradeException extends Exception {}
+}
+```
+
+---
+
+## Unit of Work
+
+Accumulates all DML operations and commits them in a single, ordered, atomic transaction.
+
+### Lightweight Implementation (No FFLIB)
+
+```apex
+public class SimpleUnitOfWork {
+
+    private List<SObject> toInsert  = new List<SObject>();
+    private List<SObject> toUpdate  = new List<SObject>();
+    private List<SObject> toDelete  = new List<SObject>();
+
+    public void registerNew(SObject record) { toInsert.add(record); }
+    public void registerDirty(SObject record) { toUpdate.add(record); }
+    public void registerDeleted(SObject record) { toDelete.add(record); }
+
+    public void commitWork() {
+        Savepoint sp = Database.setSavepoint();
+        try {
+            if (!toInsert.isEmpty()) insert toInsert;
+            if (!toUpdate.isEmpty()) update toUpdate;
+            if (!toDelete.isEmpty()) delete toDelete;
+        } catch (Exception e) {
+            Database.rollback(sp);
+            throw e;
+        }
+    }
+}
+```
+
+### FFLIB Application Factory
+
+```apex
+public class Application {
+    public static final fflib_Application.UnitOfWorkFactory UnitOfWork =
+        new fflib_Application.UnitOfWorkFactory(
+            new List<SObjectType>{
+                Account.SObjectType,
+                Contact.SObjectType,
+                Opportunity.SObjectType
+            }
+        );
+
+    public static final fflib_Application.SelectorFactory Selector =
+        new fflib_Application.SelectorFactory(
+            new Map<SObjectType, Type>{
+                Account.SObjectType     => AccountsSelector.class,
+                Opportunity.SObjectType => OpportunitiesSelector.class
+            }
+        );
+}
+```
+
+---
+
+## Pragmatic Adoption Path
+
+### Phase 1: Selector + Service (Most Immediate Value)
+
+Centralize SOQL into Selectors, business processes into Services. No FFLIB dependency needed.
+
+### Phase 2: Add Domain Layer for Trigger Logic
+
+When trigger logic grows beyond simple field defaults, introduce the Domain layer.
+
+### Phase 3: Add Unit of Work for Complex Transactions
+
+When a service needs to insert/update multiple related objects, introduce UoW for atomicity.
+
+---
+
+## FFLIB Installation
+
+```bash
+# Clone and deploy FFLIB
+git clone https://github.com/apex-enterprise-patterns/fflib-apex-common.git
+git clone https://github.com/apex-enterprise-patterns/fflib-apex-mocks.git
+sf project deploy start --source-dir fflib-apex-common/sfdx-source --target-org my-org
+sf project deploy start --source-dir fflib-apex-mocks/sfdx-source --target-org my-org
+```
+
+> FFLIB is typically deployed as unmanaged source code directly from the cloned repositories, not as a versioned managed package.
+
+---
+
+## Related
+
+- **Agents**: `sf-review-agent`, `sf-architect` — For interactive guidance
+
+### Guardrails
+
+- `sf-apex-constraints` — Governs all Apex code including enterprise pattern implementations