scc-universal 1.1.0

package/examples/agentforce-action/README.md

@@ -0,0 +1,227 @@
+# Agentforce Custom Action
+
+Custom Agentforce action using `@InvocableMethod` with structured inputs/outputs for Flow and Agent integration. Requires API version 66.0+ (Spring '26).
+
+## When to Use This Pattern
+
+- Building custom actions for Agentforce agents
+- Exposing Apex logic to Flows as invocable actions
+- Creating reusable automation building blocks with typed inputs and outputs
+- Integrating external services into Agentforce conversations
+
+## Structure
+
+```text
+force-app/main/default/
+  classes/
+    CreateCaseAction.cls            # Invocable action class
+    CreateCaseAction_Test.cls       # Test class with mock data
+```
+
+## Invocable Action Class
+
+```apex
+public with sharing class CreateCaseAction {
+
+    public class ActionInput {
+        @InvocableVariable(required=true label='Subject' description='Case subject line')
+        public String subject;
+
+        @InvocableVariable(required=true label='Description' description='Detailed case description')
+        public String description;
+
+        @InvocableVariable(label='Priority' description='Case priority: Low, Medium, High, Critical')
+        public String priority;
+
+        @InvocableVariable(label='Account ID' description='Related account ID')
+        public Id accountId;
+
+        @InvocableVariable(label='Contact ID' description='Related contact ID')
+        public Id contactId;
+    }
+
+    public class ActionOutput {
+        @InvocableVariable(label='Case ID' description='ID of the created case')
+        public Id caseId;
+
+        @InvocableVariable(label='Case Number' description='Auto-generated case number')
+        public String caseNumber;
+
+        @InvocableVariable(label='Success' description='Whether the action succeeded')
+        public Boolean success;
+
+        @InvocableVariable(label='Error Message' description='Error details if action failed')
+        public String errorMessage;
+    }
+
+    @InvocableMethod(
+        label='Create Support Case'
+        description='Creates a new support case from Agentforce or Flow input'
+        category='Support'
+    )
+    public static List<ActionOutput> createCase(List<ActionInput> inputs) {
+        List<ActionOutput> outputs = new List<ActionOutput>();
+
+        for (ActionInput input : inputs) {
+            ActionOutput output = new ActionOutput();
+            try {
+                Case newCase = new Case(
+                    Subject = input.subject,
+                    Description = input.description,
+                    Priority = String.isNotBlank(input.priority) ? input.priority : 'Medium',
+                    Status = 'New',
+                    Origin = 'Agentforce',
+                    AccountId = input.accountId,
+                    ContactId = input.contactId
+                );
+                insert newCase;
+
+                // Re-query for auto-generated fields
+                newCase = [SELECT Id, CaseNumber FROM Case WHERE Id = :newCase.Id LIMIT 1];
+
+                output.caseId = newCase.Id;
+                output.caseNumber = newCase.CaseNumber;
+                output.success = true;
+            } catch (Exception e) {
+                output.success = false;
+                output.errorMessage = e.getMessage();
+            }
+            outputs.add(output);
+        }
+
+        return outputs;
+    }
+}
+```
+
+## Test Class
+
+```apex
+@IsTest
+private class CreateCaseAction_Test {
+
+    @TestSetup
+    static void setupData() {
+        Account testAccount = new Account(Name = 'Test Corp');
+        insert testAccount;
+
+        Contact testContact = new Contact(
+            FirstName = 'Jane',
+            LastName = 'Doe',
+            AccountId = testAccount.Id,
+            Email = 'jane.doe@testcorp.com'
+        );
+        insert testContact;
+    }
+
+    @IsTest
+    static void testCreateCase_Success() {
+        Account acct = [SELECT Id FROM Account LIMIT 1];
+        Contact con = [SELECT Id FROM Contact LIMIT 1];
+
+        CreateCaseAction.ActionInput input = new CreateCaseAction.ActionInput();
+        input.subject = 'Login issue';
+        input.description = 'Customer cannot log in to portal';
+        input.priority = 'High';
+        input.accountId = acct.Id;
+        input.contactId = con.Id;
+
+        Test.startTest();
+        List<CreateCaseAction.ActionOutput> results =
+            CreateCaseAction.createCase(new List<CreateCaseAction.ActionInput>{ input });
+        Test.stopTest();
+
+        System.assertEquals(1, results.size());
+        System.assertEquals(true, results[0].success);
+        System.assertNotEquals(null, results[0].caseId);
+        System.assertNotEquals(null, results[0].caseNumber);
+
+        Case created = [SELECT Subject, Priority, Origin FROM Case WHERE Id = :results[0].caseId];
+        System.assertEquals('Login issue', created.Subject);
+        System.assertEquals('High', created.Priority);
+        System.assertEquals('Agentforce', created.Origin);
+    }
+
+    @IsTest
+    static void testCreateCase_DefaultPriority() {
+        CreateCaseAction.ActionInput input = new CreateCaseAction.ActionInput();
+        input.subject = 'General inquiry';
+        input.description = 'Question about features';
+
+        Test.startTest();
+        List<CreateCaseAction.ActionOutput> results =
+            CreateCaseAction.createCase(new List<CreateCaseAction.ActionInput>{ input });
+        Test.stopTest();
+
+        System.assertEquals(true, results[0].success);
+        Case created = [SELECT Priority FROM Case WHERE Id = :results[0].caseId];
+        System.assertEquals('Medium', created.Priority);
+    }
+
+    @IsTest
+    static void testCreateCase_BulkInvocation() {
+        List<CreateCaseAction.ActionInput> inputs = new List<CreateCaseAction.ActionInput>();
+        for (Integer i = 0; i < 50; i++) {
+            CreateCaseAction.ActionInput input = new CreateCaseAction.ActionInput();
+            input.subject = 'Bulk case ' + i;
+            input.description = 'Description for case ' + i;
+            inputs.add(input);
+        }
+
+        Test.startTest();
+        List<CreateCaseAction.ActionOutput> results = CreateCaseAction.createCase(inputs);
+        Test.stopTest();
+
+        System.assertEquals(50, results.size());
+        for (CreateCaseAction.ActionOutput output : results) {
+            System.assertEquals(true, output.success);
+        }
+    }
+}
+```
+
+## Flow Integration
+
+Once the action is deployed, it appears in Flow Builder under **Action** elements:
+
+1. Open Flow Builder and add an **Action** element
+2. Search for "Create Support Case"
+3. Map Flow variables to the `ActionInput` fields
+4. Use the `ActionOutput` fields in subsequent Flow elements
+
+```text
+Flow: Case Creation from Chat
+  Step 1: Get Input (Screen / Agentforce prompt)
+  Step 2: Action → Create Support Case
+    - Subject = {!chatSubject}
+    - Description = {!chatDescription}
+    - Priority = {!selectedPriority}
+    - Account ID = {!currentAccountId}
+  Step 3: Decision → Check {!ActionOutput.success}
+    - True → Display confirmation with {!ActionOutput.caseNumber}
+    - False → Display {!ActionOutput.errorMessage}
+```
+
+## Key Principles
+
+- Always use `with sharing` to enforce record-level security
+- Mark required inputs with `required=true` on `@InvocableVariable`
+- Provide `label` and `description` on every variable for Flow/Agent discoverability
+- Handle errors gracefully and return them in the output rather than throwing exceptions
+- Design for bulk invocation: the method receives and returns `List<>`, not single records
+- Re-query for auto-number fields after insert
+
+## Common Pitfalls
+
+- Forgetting to bulkify: inserting records inside a loop hits governor limits
+- Not handling null optional inputs, which causes NullPointerException
+- Missing `label` and `description` makes the action hard to find in Flow Builder
+- Throwing unhandled exceptions breaks the entire Flow/Agent transaction
+- Using `without sharing` inadvertently bypasses record access controls
+
+## SCC Skills
+
+- `/sf-agentforce-development` -- scaffold and review Agentforce actions
+- `/sf-apex-best-practices` -- review the action class for best practices
+- `/sf-tdd-workflow` -- write tests first, then implement the action
+- `/sf-governor-limits` -- check governor limit compliance in bulk scenarios

package/examples/apex-trigger-handler/README.md

@@ -0,0 +1,114 @@
+# Apex Trigger Handler Pattern
+
+Enterprise-grade trigger handler pattern with one trigger per object. Compatible with API version 66.0 (Spring '26).
+
+## Structure
+
+```text
+force-app/main/default/
+  classes/
+    TriggerHandler.cls           # Base handler class
+    AccountTriggerHandler.cls    # Account-specific handler
+    AccountTriggerHandler_Test.cls
+  triggers/
+    AccountTrigger.trigger       # Thin trigger — delegates to handler
+```
+
+## Base Handler
+
+```apex
+public virtual class TriggerHandler {
+
+    @TestVisible private Boolean isTriggerExecuting;
+    @TestVisible private Integer batchSize;
+
+    public TriggerHandler() {
+        this.isTriggerExecuting = Trigger.isExecuting;
+        this.batchSize = Trigger.size;
+    }
+
+    public void run() {
+        if (!validateRun()) return;
+
+        switch on Trigger.operationType {
+            when BEFORE_INSERT  { beforeInsert(Trigger.new); }
+            when BEFORE_UPDATE  { beforeUpdate(Trigger.new, Trigger.oldMap); }
+            when BEFORE_DELETE  { beforeDelete(Trigger.old, Trigger.oldMap); }
+            when AFTER_INSERT   { afterInsert(Trigger.new, Trigger.newMap); }
+            when AFTER_UPDATE   { afterUpdate(Trigger.new, Trigger.oldMap, Trigger.newMap); }
+            when AFTER_DELETE   { afterDelete(Trigger.old, Trigger.oldMap); }
+            when AFTER_UNDELETE { afterUndelete(Trigger.new, Trigger.newMap); }
+        }
+    }
+
+    @TestVisible
+    protected virtual Boolean validateRun() {
+        if (!this.isTriggerExecuting) {
+            throw new TriggerHandlerException('Trigger handler called outside of trigger execution');
+        }
+        return true;
+    }
+
+    // Override these in subclasses
+    protected virtual void beforeInsert(List<SObject> newRecords) {}
+    protected virtual void beforeUpdate(List<SObject> newRecords, Map<Id, SObject> oldMap) {}
+    protected virtual void beforeDelete(List<SObject> oldRecords, Map<Id, SObject> oldMap) {}
+    protected virtual void afterInsert(List<SObject> newRecords, Map<Id, SObject> newMap) {}
+    protected virtual void afterUpdate(List<SObject> newRecords, Map<Id, SObject> oldMap, Map<Id, SObject> newMap) {}
+    protected virtual void afterDelete(List<SObject> oldRecords, Map<Id, SObject> oldMap) {}
+    protected virtual void afterUndelete(List<SObject> newRecords, Map<Id, SObject> newMap) {}
+
+    public class TriggerHandlerException extends Exception {}
+}
+```
+
+## Trigger (Thin)
+
+```apex
+trigger AccountTrigger on Account (
+    before insert, before update, before delete,
+    after insert, after update, after delete, after undelete
+) {
+    new AccountTriggerHandler().run();
+}
+```
+
+## Handler Implementation
+
+```apex
+public class AccountTriggerHandler extends TriggerHandler {
+
+    protected override void beforeInsert(List<SObject> newRecords) {
+        List<Account> accounts = (List<Account>) newRecords;
+        for (Account acc : accounts) {
+            if (String.isBlank(acc.Industry)) {
+                acc.Industry = 'Other';
+            }
+        }
+    }
+
+    protected override void afterUpdate(List<SObject> newRecords, Map<Id, SObject> oldMap, Map<Id, SObject> newMap) {
+        List<Account> accounts = (List<Account>) newRecords;
+        List<Account> changedAccounts = new List<Account>();
+
+        for (Account acc : accounts) {
+            Account oldAcc = (Account) oldMap.get(acc.Id);
+            if (acc.OwnerId != oldAcc.OwnerId) {
+                changedAccounts.add(acc);
+            }
+        }
+
+        if (!changedAccounts.isEmpty()) {
+            AccountService.handleOwnerChanges(changedAccounts);
+        }
+    }
+}
+```
+
+## Key Principles
+
+- One trigger per object
+- Trigger delegates to handler — no logic in the trigger itself
+- Handler methods receive proper context (newRecords, oldMap, etc.)
+- All operations are bulkified (iterate over collections)
+- Business logic extracted to Service classes

package/examples/devops-pipeline/README.md

@@ -0,0 +1,325 @@
+# CI/CD Pipeline for Salesforce
+
+End-to-end DevOps pipeline with scratch org creation, source deployment, test execution, PMD scanning, and production deployment using GitHub Actions. Targets API version 66.0 (Spring '26).
+
+## When to Use This Pattern
+
+- Setting up continuous integration for a Salesforce DX project
+- Automating test execution and code quality checks on every pull request
+- Building a repeatable deployment pipeline from development to production
+- Enforcing quality gates before merging code changes
+
+## Structure
+
+```text
+.github/
+  workflows/
+    ci.yml                    # Pull request validation pipeline
+    deploy-production.yml     # Production deployment pipeline
+scripts/
+  scratch-org-setup.sh        # Scratch org creation and data load
+  run-tests.sh                # Test execution with coverage reporting
+config/
+  project-scratch-def.json    # Scratch org definition
+sfdx-project.json             # Project configuration
+```
+
+## Scratch Org Creation Script
+
+```bash
+#!/bin/bash
+# scripts/scratch-org-setup.sh
+# Creates a scratch org, pushes source, assigns permission sets, and loads data.
+
+set -euo pipefail
+
+ORG_ALIAS="${1:-ci-scratch}"
+DURATION="${2:-1}"
+
+echo "==> Creating scratch org: ${ORG_ALIAS} (duration: ${DURATION} days)"
+sf org create scratch \
+    --definition-file config/project-scratch-def.json \
+    --alias "${ORG_ALIAS}" \
+    --duration-days "${DURATION}" \
+    --set-default \
+    --wait 10
+
+echo "==> Pushing source to scratch org"
+sf project deploy start --target-org "${ORG_ALIAS}" --wait 30
+
+echo "==> Assigning permission sets"
+sf org assign permset \
+    --name AppAdmin \
+    --target-org "${ORG_ALIAS}"
+
+sf org assign permset \
+    --name IntegrationUser \
+    --target-org "${ORG_ALIAS}"
+
+echo "==> Loading sample data"
+sf data import tree \
+    --files data/Account.json,data/Contact.json,data/Opportunity.json \
+    --target-org "${ORG_ALIAS}"
+
+echo "==> Scratch org ready: ${ORG_ALIAS}"
+sf org open --target-org "${ORG_ALIAS}"
+```
+
+## Scratch Org Definition
+
+```json
+{
+    "orgName": "SCC CI Scratch Org",
+    "edition": "Developer",
+    "features": ["EnableSetPasswordInApi", "Communities", "ServiceCloud"],
+    "settings": {
+        "lightningExperienceSettings": {
+            "enableS1DesktopEnabled": true
+        },
+        "securitySettings": {
+            "passwordPolicies": {
+                "enableSetPasswordInApi": true
+            }
+        },
+        "languageSettings": {
+            "enableTranslationWorkbench": true
+        }
+    }
+}
+```
+
+## Test Execution Script
+
+```bash
+#!/bin/bash
+# scripts/run-tests.sh
+# Runs all Apex tests with coverage and fails if coverage is below threshold.
+
+set -euo pipefail
+
+ORG_ALIAS="${1:-ci-scratch}"
+COVERAGE_THRESHOLD="${2:-75}"
+
+echo "==> Running all Apex tests with code coverage"
+sf apex run test \
+    --target-org "${ORG_ALIAS}" \
+    --code-coverage \
+    --result-format human \
+    --output-dir test-results \
+    --wait 30 \
+    --test-level RunLocalTests
+
+echo "==> Checking coverage threshold (${COVERAGE_THRESHOLD}%)"
+COVERAGE=$(cat test-results/test-result-codecoverage.json \
+    | python3 -c "
+import json, sys
+data = json.load(sys.stdin)
+total_lines = sum(r.get('totalLines', 0) for r in data)
+covered_lines = sum(r.get('totalCovered', 0) for r in data)
+pct = (covered_lines / total_lines * 100) if total_lines > 0 else 0
+print(f'{pct:.1f}')
+")
+
+echo "==> Overall coverage: ${COVERAGE}%"
+
+if (( $(echo "${COVERAGE} < ${COVERAGE_THRESHOLD}" | bc -l) )); then
+    echo "ERROR: Coverage ${COVERAGE}% is below threshold ${COVERAGE_THRESHOLD}%"
+    exit 1
+fi
+
+echo "==> Coverage check passed"
+```
+
+## PMD Scanning Integration
+
+```bash
+#!/bin/bash
+# Run SFDX Scanner with PMD rules as a CI gate
+
+set -euo pipefail
+
+echo "==> Running PMD security and best practices scan"
+sf scanner run \
+    --target "force-app/main/default/classes/**/*.cls" \
+    --category "Security,Best Practices,Performance" \
+    --engine pmd \
+    --format json \
+    --outfile scanner-results.json \
+    --severity-threshold 2
+
+VIOLATIONS=$(cat scanner-results.json | python3 -c "
+import json, sys
+data = json.load(sys.stdin)
+count = len(data) if isinstance(data, list) else 0
+print(count)
+")
+
+echo "==> Found ${VIOLATIONS} violation(s)"
+
+if [ "${VIOLATIONS}" -gt 0 ]; then
+    echo "==> Violations found. See scanner-results.json for details."
+    sf scanner run \
+        --target "force-app/main/default/classes/**/*.cls" \
+        --category "Security,Best Practices,Performance" \
+        --engine pmd \
+        --format table \
+        --severity-threshold 2
+    exit 1
+fi
+
+echo "==> PMD scan passed"
+```
+
+## GitHub Actions: Pull Request Validation
+
+```yaml
+# .github/workflows/ci.yml
+name: Salesforce CI
+
+on:
+  pull_request:
+    branches: [main, develop]
+    paths:
+      - 'force-app/**'
+      - 'config/**'
+      - 'sfdx-project.json'
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Install Salesforce CLI
+        run: npm install -g @salesforce/cli
+
+      - name: Install SFDX Scanner
+        run: sf plugins install @salesforce/sfdx-scanner
+
+      - name: Authenticate Dev Hub
+        run: |
+          echo "${SFDX_AUTH_URL}" > auth.txt
+          sf org login sfdx-url --sfdx-url-file auth.txt --alias devhub --set-default-dev-hub
+          rm auth.txt
+        env:
+          SFDX_AUTH_URL: ${{ secrets.SFDX_DEVHUB_AUTH_URL }}
+
+      - name: Create Scratch Org
+        run: |
+          sf org create scratch \
+            --definition-file config/project-scratch-def.json \
+            --alias ci-scratch \
+            --duration-days 1 \
+            --set-default \
+            --wait 15
+
+      - name: Deploy Source
+        run: sf project deploy start --target-org ci-scratch --wait 30
+
+      - name: Run Apex Tests
+        run: |
+          sf apex run test \
+            --target-org ci-scratch \
+            --code-coverage \
+            --result-format human \
+            --output-dir test-results \
+            --wait 30 \
+            --test-level RunLocalTests
+
+      - name: Upload Test Results
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: apex-test-results
+          path: test-results/
+
+      - name: Run PMD Scanner
+        run: |
+          sf scanner run \
+            --target "force-app/main/default/classes/**/*.cls" \
+            --category "Security,Best Practices" \
+            --engine pmd \
+            --format table \
+            --severity-threshold 2
+
+      - name: Delete Scratch Org
+        if: always()
+        run: sf org delete scratch --target-org ci-scratch --no-prompt
+```
+
+## GitHub Actions: Production Deployment
+
+```yaml
+# .github/workflows/deploy-production.yml
+name: Deploy to Production
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'force-app/**'
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    environment: production
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Install Salesforce CLI
+        run: npm install -g @salesforce/cli
+
+      - name: Authenticate Production
+        run: |
+          echo "${SFDX_AUTH_URL}" > auth.txt
+          sf org login sfdx-url --sfdx-url-file auth.txt --alias production
+          rm auth.txt
+        env:
+          SFDX_AUTH_URL: ${{ secrets.SFDX_PROD_AUTH_URL }}
+
+      - name: Validate Deployment (Check Only)
+        run: |
+          sf project deploy start \
+            --target-org production \
+            --test-level RunLocalTests \
+            --dry-run \
+            --wait 60
+
+      - name: Deploy to Production
+        run: |
+          sf project deploy start \
+            --target-org production \
+            --test-level RunLocalTests \
+            --wait 60
+
+      - name: Verify Deployment
+        run: |
+          sf project deploy report --target-org production
+```
+
+## Key Principles
+
+- Every pull request validates in a fresh scratch org to catch deployment issues early
+- Tests run with `RunLocalTests` to avoid executing managed package tests
+- PMD scanning gates the pipeline: violations above a severity threshold fail the build
+- Production deployments use a `--dry-run` validation step before the real deploy
+- Scratch orgs are deleted after each CI run to conserve limits
+- Auth URLs are stored as encrypted GitHub Secrets, never committed to source
+
+## Common Pitfalls
+
+- Not deleting scratch orgs in CI, which exhausts the daily scratch org limit
+- Hardcoding the Dev Hub username instead of using auth URL files
+- Skipping `RunLocalTests` in validation, then discovering test failures during real deploy
+- Forgetting to install required plugins (scanner) in the CI environment
+- Not setting `--wait` timeouts, causing CI jobs to hang indefinitely
+- Storing SFDX auth URLs or tokens in the repository instead of secrets
+
+## SCC Skills
+
+- `/sf-deployment` -- validate and deploy metadata to a target org
+- `/sf-devops-ci-cd` -- CI/CD pipeline patterns with scratch orgs
+- `/sf-build-fix` -- diagnose and fix deployment failures
+- `/sf-apex-testing` -- run Apex tests with coverage analysis