sf-forcekit 1.0.0

package/templates/ai-dir/source-of-truth.md

@@ -0,0 +1,180 @@
+# Source of Truth
+
+> 🚫 **NEVER GUESS. ALWAYS VERIFY.**
+> This file tells agents WHERE to look things up instead of hallucinating answers.
+> If you can't verify something, say "I'm not sure — please verify" instead of making it up.
+
+---
+
+## Golden Rule
+
+> [!CAUTION]
+> **If you are not 100% certain something exists (a field, object, class, method, CLI flag, API endpoint), you MUST verify it using the methods below. Making up Salesforce metadata is the #1 source of broken code.**
+
+---
+
+## How to Verify: Metadata
+
+### Objects & Fields — Run SOQL
+
+```bash
+# Check if an object exists
+sf data query --query "SELECT QualifiedApiName FROM EntityDefinition WHERE QualifiedApiName = 'Account'" \
+  --target-org <target_org> --use-tooling-api
+
+# Check if a field exists on an object
+sf data query --query "SELECT QualifiedApiName, DataType FROM FieldDefinition WHERE EntityDefinition.QualifiedApiName = 'Account' AND QualifiedApiName = 'Industry'" \
+  --target-org <target_org> --use-tooling-api
+
+# List ALL custom fields on an object
+sf data query --query "SELECT QualifiedApiName, DataType FROM FieldDefinition WHERE EntityDefinition.QualifiedApiName = 'MyObject__c'" \
+  --target-org <target_org> --use-tooling-api
+
+# List ALL custom objects in the org
+sf data query --query "SELECT QualifiedApiName FROM EntityDefinition WHERE QualifiedApiName LIKE '%__c'" \
+  --target-org <target_org> --use-tooling-api
+```
+
+### Apex Classes — Check Tooling API
+
+```bash
+# Check if an Apex class exists
+sf data query --query "SELECT Name, Status FROM ApexClass WHERE Name = 'AccountService'" \
+  --target-org <target_org> --use-tooling-api
+
+# List all Apex classes
+sf data query --query "SELECT Name, Status, ApiVersion FROM ApexClass ORDER BY Name" \
+  --target-org <target_org> --use-tooling-api
+```
+
+### Flows — Check Tooling API
+
+```bash
+# List active flows
+sf data query --query "SELECT DeveloperName, ProcessType, Status FROM FlowDefinitionView WHERE IsActive = true" \
+  --target-org <target_org> --use-tooling-api
+```
+
+### Custom Labels
+
+```bash
+sf data query --query "SELECT Name, Value FROM ExternalString" \
+  --target-org <target_org> --use-tooling-api
+```
+
+### Named Credentials
+
+```bash
+sf data query --query "SELECT DeveloperName, Endpoint FROM NamedCredential" \
+  --target-org <target_org> --use-tooling-api
+```
+
+### Custom Metadata Types
+
+```bash
+# List CMDT types
+sf data query --query "SELECT QualifiedApiName FROM EntityDefinition WHERE QualifiedApiName LIKE '%__mdt'" \
+  --target-org <target_org> --use-tooling-api
+
+# Query CMDT records
+sf data query --query "SELECT DeveloperName, Label FROM MyConfig__mdt" \
+  --target-org <target_org>
+```
+
+---
+
+## How to Verify: Local Project Files
+
+Before referencing a class, trigger, or component — check if it exists in the project:
+
+```bash
+# Check if an Apex class exists locally
+ls force-app/main/default/classes/AccountService.cls
+
+# Check if a trigger exists
+ls force-app/main/default/triggers/AccountTrigger.trigger
+
+# Check if an LWC exists
+ls force-app/main/default/lwc/accountSummary/
+
+# Search for a field reference across the project
+grep -r "MyField__c" force-app/
+
+# Find all classes that reference a specific object
+grep -r "MyObject__c" force-app/main/default/classes/
+```
+
+---
+
+## How to Verify: CLI Commands & Flags
+
+```bash
+# Don't guess CLI flags — check them
+sf project deploy start --help
+sf data query --help
+sf apex run test --help
+sf org open --help
+```
+
+---
+
+## How to Verify: Apex Methods & Classes
+
+### Standard Library — Trust These
+
+These Apex classes/methods are part of the platform and always exist:
+
+| Class | Common Methods | Safe to Use |
+|-------|---------------|-------------|
+| `Database` | `insert()`, `update()`, `query()`, `setSavepoint()`, `rollback()` | ✅ |
+| `System` | `debug()`, `assertEquals()`, `runAs()`, `enqueueJob()` | ✅ |
+| `Limits` | `getQueries()`, `getDmlStatements()`, `getCpuTime()`, `getHeapSize()` | ✅ |
+| `Security` | `stripInaccessible()` | ✅ v48.0+ |
+| `JSON` | `serialize()`, `deserialize()`, `deserializeUntyped()` | ✅ |
+| `String` | `isBlank()`, `escapeSingleQuotes()`, `substringAfter()` | ✅ |
+| `Http` / `HttpRequest` / `HttpResponse` | `send()`, `setEndpoint()`, `setMethod()` | ✅ |
+| `Test` | `startTest()`, `stopTest()`, `setMock()`, `isRunningTest()` | ✅ |
+| `EventBus` | `publish()` | ✅ |
+| `UserInfo` | `getUserId()`, `getUserName()`, `getOrganizationId()` | ✅ |
+| `Schema` | `getGlobalDescribe()`, `describeSObjects()` | ✅ |
+
+### Custom Classes — ALWAYS VERIFY
+
+Never assume a custom class (`*Service`, `*Selector`, `*Handler`, `Logger`, `TestDataFactory`) exists.
+Check the local project files or `inventory.md` first.
+
+---
+
+## Common Hallucination Traps
+
+| Trap | What Agents Get Wrong | How to Avoid |
+|------|----------------------|-------------|
+| **Field names** | Inventing `Account.HealthScore__c` that doesn't exist | Query `FieldDefinition` via Tooling API |
+| **Object names** | Using `OrderItem` vs `OrderProduct` vs `OpportunityLineItem` | Query `EntityDefinition` via Tooling API |
+| **API methods** | Making up `Database.upsertImmediate()` (doesn't exist) | Only use methods from the standard library table above |
+| **CLI flags** | Inventing `--run-all-tests` (actual: `--test-level RunAllTestsInOrg`) | Run `--help` on the command first |
+| **Sharing keywords** | Using `inherited sharing` incorrectly | Only: `with sharing`, `without sharing`, `inherited sharing` |
+| **SOQL keywords** | Using `WITH SYSTEM_MODE` in wrong context | Only `WITH USER_MODE` or `WITH SECURITY_ENFORCED` in SOQL |
+| **Governor limits** | Wrong numbers (e.g., "200 SOQL queries per transaction") | Reference `org-context.md` — it's 100 |
+| **Trigger events** | Using `before undelete` (doesn't exist) | Valid: before/after insert/update/delete, after undelete |
+| **LWC decorators** | Making up `@track` behavior (auto-reactive since v40) | Check current LWC docs |
+| **Flow types** | Referencing "Before-Delete Flow" (doesn't exist natively) | Before-Save (insert/update only), After-Save, Scheduled, etc. |
+
+---
+
+## Confidence Signals
+
+When you're not certain about something, use these prefixes in your response:
+
+| Prefix | Meaning |
+|--------|---------|
+| ✅ **Verified** | Confirmed via CLI query, file check, or documentation |
+| ⚠️ **Assumed** | Reasonable assumption but not verified — flag for human review |
+| ❓ **Uncertain** | Not sure — explicitly ask the developer to confirm |
+
+Example:
+```
+✅ Verified: Account.Industry field exists (standard field)
+⚠️ Assumed: Account.HealthScore__c exists based on architecture.md — please confirm
+❓ Uncertain: Not sure if the org has Platform Events enabled — check org-context.md
+```

package/templates/ai-dir/templates/Selector.cls

@@ -0,0 +1,113 @@
+/**
+ * @description Selector class for {Object} SOQL queries.
+ *              ALL SOQL for {Object} lives here — nowhere else.
+ *              Called by {Object}Service and controllers.
+ *
+ * Architecture: Trigger → Handler → Service → SELECTOR
+ *
+ * @author  [Your Name]
+ * @date    [Date]
+ */
+public with sharing class {Object}Selector {
+
+    // ─── Field Sets ─────────────────────────────────────────────
+
+    /**
+     * @description Default fields for standard queries.
+     *              Update this list when adding new fields to queries.
+     */
+    private static final String DEFAULT_FIELDS =
+        'Id, Name, Status__c, OwnerId, CreatedDate, LastModifiedDate';
+
+    // ─── Query Methods ──────────────────────────────────────────
+
+    /**
+     * @description Gets records by their Ids.
+     * @param ids Set of record Ids to retrieve.
+     * @return List of records with default fields.
+     */
+    public static List<{Object__c}> getByIds(Set<Id> ids) {
+        return [
+            SELECT Id, Name, Status__c, OwnerId, CreatedDate
+            FROM {Object__c}
+            WHERE Id IN :ids
+            WITH USER_MODE
+        ];
+    }
+
+    /**
+     * @description Gets records by related Account Ids.
+     * @param accountIds Set of Account Ids.
+     * @return List of records ordered by CreatedDate descending.
+     */
+    public static List<{Object__c}> getByAccountIds(Set<Id> accountIds) {
+        return [
+            SELECT Id, Name, Status__c, Account__c, Account__r.Name
+            FROM {Object__c}
+            WHERE Account__c IN :accountIds
+            WITH USER_MODE
+            ORDER BY CreatedDate DESC
+        ];
+    }
+
+    /**
+     * @description Gets records by status.
+     * @param statuses Set of status values to filter by.
+     * @return List of matching records.
+     */
+    public static List<{Object__c}> getByStatus(Set<String> statuses) {
+        return [
+            SELECT Id, Name, Status__c, OwnerId
+            FROM {Object__c}
+            WHERE Status__c IN :statuses
+            WITH USER_MODE
+            ORDER BY LastModifiedDate DESC
+        ];
+    }
+
+    /**
+     * @description Gets records with child relationships.
+     * @param ids Set of record Ids.
+     * @return List of records with child records.
+     */
+    public static List<{Object__c}> getWithChildren(Set<Id> ids) {
+        return [
+            SELECT Id, Name, Status__c,
+                (SELECT Id, Name FROM ChildObjects__r ORDER BY CreatedDate)
+            FROM {Object__c}
+            WHERE Id IN :ids
+            WITH USER_MODE
+        ];
+    }
+
+    /**
+     * @description Counts records by status (aggregate query).
+     * @return List of AggregateResult with Status__c and record count.
+     */
+    public static List<AggregateResult> countByStatus() {
+        return [
+            SELECT Status__c, COUNT(Id) recordCount
+            FROM {Object__c}
+            WITH USER_MODE
+            GROUP BY Status__c
+        ];
+    }
+
+    /**
+     * @description Searches records by name (SOSL alternative using LIKE).
+     * @param searchTerm The term to search for.
+     * @param limitSize Maximum results to return.
+     * @return List of matching records.
+     */
+    public static List<{Object__c}> searchByName(String searchTerm, Integer limitSize) {
+        String safeTerm = '%' + String.escapeSingleQuotes(searchTerm) + '%';
+        return [
+            SELECT Id, Name, Status__c
+            FROM {Object__c}
+            WHERE Name LIKE :safeTerm
+            WITH USER_MODE
+            ORDER BY Name
+            LIMIT :limitSize
+        ];
+    }
+}

package/templates/ai-dir/templates/Service.cls

@@ -0,0 +1,132 @@
+/**
+ * @description Service class for {Object} business logic.
+ *              All business logic for {Object} lives here.
+ *              Called by {Object}TriggerHandler and controllers.
+ *              Calls {Object}Selector for data access.
+ *
+ * Architecture: Trigger → Handler → SERVICE → Selector
+ *
+ * @author  [Your Name]
+ * @date    [Date]
+ */
+public with sharing class {Object}Service {
+
+    // ─── Custom Exception ───────────────────────────────────────
+
+    public class {Object}ServiceException extends Exception {}
+
+    // ─── Trigger Context Methods ────────────────────────────────
+
+    /**
+     * @description Handles before insert logic.
+     * @param newRecords List of new records being inserted.
+     */
+    public static void onBeforeInsert(List<{Object__c}> newRecords) {
+        setDefaults(newRecords);
+        validate(newRecords);
+    }
+
+    /**
+     * @description Handles after insert logic.
+     * @param newRecords List of newly inserted records.
+     */
+    public static void onAfterInsert(List<{Object__c}> newRecords) {
+        // Example: Create related records, publish events
+    }
+
+    /**
+     * @description Handles before update logic.
+     * @param newRecords List of records with new values.
+     * @param oldMap Map of records with previous values.
+     */
+    public static void onBeforeUpdate(
+        List<{Object__c}> newRecords,
+        Map<Id, {Object__c}> oldMap
+    ) {
+        List<{Object__c}> statusChanged = filterStatusChanged(newRecords, oldMap);
+        if (!statusChanged.isEmpty()) {
+            validateStatusTransition(statusChanged, oldMap);
+        }
+    }
+
+    /**
+     * @description Handles after update logic.
+     * @param newRecords List of records with new values.
+     * @param oldMap Map of records with previous values.
+     */
+    public static void onAfterUpdate(
+        List<{Object__c}> newRecords,
+        Map<Id, {Object__c}> oldMap
+    ) {
+        List<{Object__c}> statusChanged = filterStatusChanged(newRecords, oldMap);
+        if (!statusChanged.isEmpty()) {
+            processStatusChange(statusChanged, oldMap);
+        }
+    }
+
+    // ─── Public Service Methods ─────────────────────────────────
+
+    /**
+     * @description Creates {Object} records from DTOs.
+     * @param dtos List of data transfer objects.
+     * @return List of created records with Ids.
+     */
+    public static List<{Object__c}> createFromDTOs(List<{Object}DTO> dtos) {
+        List<{Object__c}> records = new List<{Object__c}>();
+        for ({Object}DTO dto : dtos) {
+            records.add(dto.toSObject());
+        }
+
+        SObjectAccessDecision decision = Security.stripInaccessible(
+            AccessType.CREATABLE, records
+        );
+        insert decision.getRecords();
+        return decision.getRecords();
+    }
+
+    // ─── Private Helper Methods ─────────────────────────────────
+
+    private static void setDefaults(List<{Object__c}> records) {
+        for ({Object__c} record : records) {
+            if (record.Status__c == null) {
+                record.Status__c = 'New';
+            }
+        }
+    }
+
+    private static void validate(List<{Object__c}> records) {
+        for ({Object__c} record : records) {
+            if (String.isBlank(record.Name)) {
+                record.Name.addError('Name is required.');
+            }
+        }
+    }
+
+    private static List<{Object__c}> filterStatusChanged(
+        List<{Object__c}> newRecords,
+        Map<Id, {Object__c}> oldMap
+    ) {
+        List<{Object__c}> changed = new List<{Object__c}>();
+        for ({Object__c} record : newRecords) {
+            {Object__c} oldRecord = oldMap.get(record.Id);
+            if (record.Status__c != oldRecord.Status__c) {
+                changed.add(record);
+            }
+        }
+        return changed;
+    }
+
+    private static void validateStatusTransition(
+        List<{Object__c}> records,
+        Map<Id, {Object__c}> oldMap
+    ) {
+        // Validate allowed status transitions
+    }
+
+    private static void processStatusChange(
+        List<{Object__c}> records,
+        Map<Id, {Object__c}> oldMap
+    ) {
+        // Process downstream effects of status change
+    }
+}

package/templates/ai-dir/templates/TestClass.cls

@@ -0,0 +1,143 @@
+/**
+ * @description Test class for {ClassName}.
+ *              Tests cover: bulk (200+), positive, negative, and permission scenarios.
+ *
+ * @author  [Your Name]
+ * @date    [Date]
+ */
+@IsTest
+private class {ClassName}Test {
+
+    // ─── Test Data Setup ────────────────────────────────────────
+
+    @TestSetup
+    static void setupTestData() {
+        // Create bulk test data (200+ records)
+        List<Account> accounts = TestDataFactory.createAccounts(200);
+        insert accounts;
+
+        // Create related records if needed
+        // List<Contact> contacts = TestDataFactory.createContacts(accounts, 2);
+        // insert contacts;
+    }
+
+    // ─── Positive Tests ─────────────────────────────────────────
+
+    @IsTest
+    static void testMethod_PositiveScenario() {
+        // Arrange
+        List<Account> accounts = [SELECT Id, Name FROM Account];
+        System.assertEquals(200, accounts.size(), 'TestSetup should create 200 accounts');
+
+        // Act
+        Test.startTest();
+        // Call the method under test
+        Test.stopTest();
+
+        // Assert
+        // System.assertEquals(expected, actual, 'Descriptive message');
+    }
+
+    // ─── Bulk Tests ─────────────────────────────────────────────
+
+    @IsTest
+    static void testMethod_Bulk200Records() {
+        // Arrange
+        List<Account> accounts = [SELECT Id FROM Account];
+
+        // Act
+        Test.startTest();
+        // Process all 200 records
+        Test.stopTest();
+
+        // Assert — no governor limit exceptions
+        // Verify all records processed correctly
+    }
+
+    // ─── Negative Tests ─────────────────────────────────────────
+
+    @IsTest
+    static void testMethod_NullInput() {
+        Boolean exceptionThrown = false;
+
+        Test.startTest();
+        try {
+            // Call method with null/invalid input
+        } catch (Exception e) {
+            exceptionThrown = true;
+            System.assert(
+                e.getMessage().contains('expected error text'),
+                'Exception should contain meaningful message: ' + e.getMessage()
+            );
+        }
+        Test.stopTest();
+
+        System.assert(exceptionThrown, 'Should throw exception for null input');
+    }
+
+    @IsTest
+    static void testMethod_InvalidData() {
+        // Arrange — create invalid record
+
+        // Act & Assert
+        Test.startTest();
+        try {
+            // Attempt invalid operation
+            System.assert(false, 'Should have thrown an exception');
+        } catch (DmlException e) {
+            System.assert(
+                e.getMessage().contains('REQUIRED_FIELD_MISSING')
+                || e.getMessage().contains('FIELD_CUSTOM_VALIDATION_EXCEPTION'),
+                'Should fail validation: ' + e.getMessage()
+            );
+        }
+        Test.stopTest();
+    }
+
+    // ─── Permission Tests ───────────────────────────────────────
+
+    @IsTest
+    static void testMethod_RestrictedUser() {
+        User restrictedUser = TestDataFactory.createStandardUser();
+        insert restrictedUser;
+
+        System.runAs(restrictedUser) {
+            Test.startTest();
+            // Test with restricted permissions
+            // Verify FLS/CRUD enforcement
+            Test.stopTest();
+        }
+    }
+
+    // ─── Callout Tests (if applicable) ──────────────────────────
+
+    /*
+    @IsTest
+    static void testCallout_Success() {
+        Test.setMock(HttpCalloutMock.class, new MockSuccessResponse());
+
+        Test.startTest();
+        // Call method that makes callout
+        Test.stopTest();
+
+        // Assert response handled correctly
+    }
+
+    @IsTest
+    static void testCallout_Failure() {
+        Test.setMock(HttpCalloutMock.class, new MockFailureResponse());
+
+        Test.startTest();
+        try {
+            // Call method that makes callout
+        } catch (IntegrationException e) {
+            System.assert(true, 'Should handle callout failure gracefully');
+        }
+        Test.stopTest();
+    }
+    */
+
+    // ─── Helper Methods ─────────────────────────────────────────
+
+    // Add test-specific helpers here
+}

package/templates/ai-dir/templates/TriggerHandler.cls

@@ -0,0 +1,67 @@
+/**
+ * @description Base class for trigger handlers.
+ *              Extend this class for each object's trigger handler.
+ *              Delegates trigger context to virtual methods.
+ *
+ * Usage:
+ *   trigger AccountTrigger on Account (...) {
+ *       new AccountTriggerHandler().run();
+ *   }
+ *
+ * @author  [Your Name]
+ * @date    [Date]
+ */
+public virtual with sharing class TriggerHandler {
+
+    // Recursion prevention
+    private static Set<String> bypassedHandlers = new Set<String>();
+
+    /**
+     * @description Main entry point. Routes trigger context to virtual methods.
+     */
+    public void run() {
+        String handlerName = String.valueOf(this).substring(0, String.valueOf(this).indexOf(':'));
+
+        if (bypassedHandlers.contains(handlerName)) {
+            return;
+        }
+
+        switch on Trigger.operationType {
+            when BEFORE_INSERT  { this.beforeInsert(); }
+            when BEFORE_UPDATE  { this.beforeUpdate(); }
+            when BEFORE_DELETE  { this.beforeDelete(); }
+            when AFTER_INSERT   { this.afterInsert(); }
+            when AFTER_UPDATE   { this.afterUpdate(); }
+            when AFTER_DELETE   { this.afterDelete(); }
+            when AFTER_UNDELETE { this.afterUndelete(); }
+        }
+    }
+
+    // ─── Virtual Methods (Override in Subclass) ─────────────────
+
+    protected virtual void beforeInsert()  {}
+    protected virtual void beforeUpdate()  {}
+    protected virtual void beforeDelete()  {}
+    protected virtual void afterInsert()   {}
+    protected virtual void afterUpdate()   {}
+    protected virtual void afterDelete()   {}
+    protected virtual void afterUndelete() {}
+
+    // ─── Bypass Control ─────────────────────────────────────────
+
+    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);
+    }
+}