sf-forcekit 1.0.0

package/templates/ai-dir/prompts/testing.md

@@ -0,0 +1,269 @@
+# Test Class Generation Rules
+
+> Instructions for AI agents when generating Apex test classes.
+
+---
+
+## Absolute Rules
+
+| Rule | Enforcement |
+|------|------------|
+| `SeeAllData=true` | **BANNED** — never use, no exceptions |
+| Minimum coverage | **75%** (target **90%+**) |
+| Test data | Always use `@TestSetup` or `TestDataFactory` |
+| Assertions | Every test must have `System.assert*` with meaningful message |
+| Bulk testing | At least one test with **200+ records** |
+| Negative paths | At least one test for error/exception scenarios |
+
+---
+
+## Test Class Structure
+
+```apex
+@IsTest
+private class {ClassName}Test {
+
+    // ─── Shared Test Data ───────────────────────────────────────
+    @TestSetup
+    static void setupTestData() {
+        // Create all shared test data here
+        // This runs once, data is rolled back per test method
+        List<Account> accounts = TestDataFactory.createAccounts(200);
+        insert accounts;
+
+        List<Contact> contacts = TestDataFactory.createContacts(accounts, 2); // 2 per account
+        insert contacts;
+    }
+
+    // ─── Positive Tests ─────────────────────────────────────────
+
+    @IsTest
+    static void testMethodName_PositiveScenario() {
+        // Arrange
+        List<Account> accounts = [SELECT Id, Name FROM Account];
+
+        // Act
+        Test.startTest();
+        List<Account> result = AccountService.processAccounts(accounts);
+        Test.stopTest();
+
+        // Assert
+        System.assertEquals(200, result.size(), 'Should process all 200 accounts');
+        System.assertNotEquals(null, result[0].Name, 'Account name should not be null');
+    }
+
+    // ─── Bulk Tests ─────────────────────────────────────────────
+
+    @IsTest
+    static void testMethodName_Bulk200Records() {
+        // Arrange
+        List<Account> accounts = [SELECT Id FROM Account];
+        System.assertEquals(200, accounts.size(), 'Test setup should create 200 accounts');
+
+        // Act
+        Test.startTest();
+        AccountService.bulkOperation(accounts);
+        Test.stopTest();
+
+        // Assert — verify no governor limit exceptions occurred
+        List<Account> updated = [SELECT Id, Status__c FROM Account WHERE Id IN :accounts];
+        for (Account a : updated) {
+            System.assertEquals('Processed', a.Status__c, 'All accounts should be processed');
+        }
+    }
+
+    // ─── Negative Tests ─────────────────────────────────────────
+
+    @IsTest
+    static void testMethodName_NullInput() {
+        Boolean exceptionThrown = false;
+
+        Test.startTest();
+        try {
+            AccountService.processAccounts(null);
+        } catch (AccountService.AccountProcessingException e) {
+            exceptionThrown = true;
+            System.assert(e.getMessage().contains('cannot be null'),
+                'Exception message should indicate null input');
+        }
+        Test.stopTest();
+
+        System.assert(exceptionThrown, 'Should throw exception for null input');
+    }
+
+    @IsTest
+    static void testMethodName_InvalidData() {
+        // Arrange
+        Account invalidAccount = new Account(); // Missing required fields
+
+        // Act & Assert
+        Test.startTest();
+        try {
+            insert invalidAccount;
+            System.assert(false, 'Should have thrown DmlException');
+        } catch (DmlException e) {
+            System.assert(e.getMessage().contains('REQUIRED_FIELD_MISSING'),
+                'Should fail on required field validation');
+        }
+        Test.stopTest();
+    }
+
+    // ─── Permission Tests ───────────────────────────────────────
+
+    @IsTest
+    static void testMethodName_RestrictedUser() {
+        // Create a user with minimal permissions
+        User restrictedUser = TestDataFactory.createStandardUser();
+        insert restrictedUser;
+
+        System.runAs(restrictedUser) {
+            Test.startTest();
+            try {
+                AccountService.processAccounts([SELECT Id FROM Account]);
+                // If security is properly enforced, this should throw
+            } catch (System.NoAccessException e) {
+                System.assert(true, 'Restricted user should not have access');
+            }
+            Test.stopTest();
+        }
+    }
+
+    // ─── Callout Mock Tests ─────────────────────────────────────
+
+    @IsTest
+    static void testCallout_Success() {
+        Test.setMock(HttpCalloutMock.class, new ExternalApiMockSuccess());
+
+        Test.startTest();
+        ApiResponseDTO response = ExternalApiService.callExternalApi('/endpoint', 'GET', null);
+        Test.stopTest();
+
+        System.assertNotEquals(null, response, 'Response should not be null');
+        System.assertEquals('success', response.status, 'API call should succeed');
+    }
+
+    @IsTest
+    static void testCallout_Failure() {
+        Test.setMock(HttpCalloutMock.class, new ExternalApiMockFailure());
+
+        Boolean exceptionThrown = false;
+        Test.startTest();
+        try {
+            ExternalApiService.callExternalApi('/endpoint', 'GET', null);
+        } catch (IntegrationException e) {
+            exceptionThrown = true;
+        }
+        Test.stopTest();
+
+        System.assert(exceptionThrown, 'Should throw IntegrationException on API failure');
+    }
+}
+```
+
+---
+
+## TestDataFactory Pattern
+
+```apex
+@IsTest
+public class TestDataFactory {
+
+    public static List<Account> createAccounts(Integer count) {
+        List<Account> accounts = new List<Account>();
+        for (Integer i = 0; i < count; i++) {
+            accounts.add(new Account(
+                Name = 'Test Account ' + i,
+                Industry = 'Technology'
+            ));
+        }
+        return accounts; // Don't insert — let caller decide
+    }
+
+    public static List<Contact> createContacts(List<Account> accounts, Integer perAccount) {
+        List<Contact> contacts = new List<Contact>();
+        for (Account a : accounts) {
+            for (Integer i = 0; i < perAccount; i++) {
+                contacts.add(new Contact(
+                    FirstName = 'Test',
+                    LastName = 'Contact ' + i,
+                    AccountId = a.Id,
+                    Email = 'test' + i + '@' + a.Id + '.test'
+                ));
+            }
+        }
+        return contacts;
+    }
+
+    public static User createStandardUser() {
+        Profile p = [SELECT Id FROM Profile WHERE Name = 'Standard User' LIMIT 1];
+        return new User(
+            FirstName = 'Test',
+            LastName = 'User',
+            Email = 'testuser@test.salesforce.com',
+            Username = 'testuser' + DateTime.now().getTime() + '@test.salesforce.com',
+            Alias = 'tuser',
+            TimeZoneSidKey = 'America/Los_Angeles',
+            LocaleSidKey = 'en_US',
+            EmailEncodingKey = 'UTF-8',
+            LanguageLocaleKey = 'en_US',
+            ProfileId = p.Id
+        );
+    }
+}
+```
+
+---
+
+## HttpCalloutMock Pattern
+
+```apex
+@IsTest
+public class ExternalApiMockSuccess implements HttpCalloutMock {
+    public HTTPResponse respond(HTTPRequest req) {
+        HttpResponse res = new HttpResponse();
+        res.setStatusCode(200);
+        res.setHeader('Content-Type', 'application/json');
+        res.setBody('{"status":"success","data":[]}');
+        return res;
+    }
+}
+
+@IsTest
+public class ExternalApiMockFailure implements HttpCalloutMock {
+    public HTTPResponse respond(HTTPRequest req) {
+        HttpResponse res = new HttpResponse();
+        res.setStatusCode(500);
+        res.setBody('{"error":"Internal Server Error"}');
+        return res;
+    }
+}
+```
+
+---
+
+## Assertion Best Practices
+
+```apex
+// ✅ GOOD — Meaningful messages
+System.assertEquals(200, accounts.size(), 'Should return 200 accounts for bulk test');
+System.assertNotEquals(null, account.Name, 'Account name should be populated after processing');
+System.assert(result.isSuccess(), 'DML should succeed for valid records: ' + result.getErrors());
+
+// ❌ BAD — No context
+System.assertEquals(200, accounts.size());
+System.assert(result.isSuccess());
+```
+
+---
+
+## Checklist Before Returning Test Code
+
+- [ ] `@IsTest` annotation on class (private class)
+- [ ] `@TestSetup` for shared data
+- [ ] NO `SeeAllData=true` anywhere
+- [ ] `Test.startTest()` / `Test.stopTest()` wrapping the operation under test
+- [ ] At least one bulk test (200+ records)
+- [ ] At least one negative/error path test
+- [ ] All assertions have descriptive messages
+- [ ] HttpCalloutMock used for callout tests
+- [ ] Follows naming convention: `{ClassName}Test`

package/templates/ai-dir/rules.md

@@ -0,0 +1,238 @@
+# Agent Rules — READ THIS FIRST
+
+> This is the master instruction file for any AI agent working in this Salesforce project.
+> Read this file BEFORE doing anything else. Follow every rule without exception.
+
+---
+
+## 1. Read Order
+
+When starting a new session, read files by tier. Read T0 always. Read T1–T3 as needed.
+
+### T0 — Always (Every Session)
+
+1. **This file** (`rules.md`) — Agent behavior rules
+2. **`org-context.local.md`** (or **`org-context.md`** if local does not exist) — Active Org details, CLI config, limits
+3. **`inventory.md`** — What actually exists in this project (objects, classes, components)
+4. **`current-state.md`** — What's happening NOW (session log, active work, blockers, next steps)
+
+### T1 — Before Writing Code
+
+5. **`conventions.md`** — Coding standards (Apex, LWC, Flow)
+6. **`source-of-truth.md`** — How to verify before you generate
+7. **`prompts/{relevant}.md`** — Generation rules for the specific task
+
+### T2 — When Task Involves Design, Tests, or Performance
+
+8. **`architecture.md`** — Data model, layers, integrations
+9. **`testing-strategy.md`** — Test philosophy, patterns, coverage rules
+10. **`performance.md`** — Governor limits, SOQL optimization, async patterns
+
+### T3 — Reference (Read When Specifically Needed)
+
+11. **`commands.md`** — sf CLI cookbook
+12. **`deployment.md`** — Deploy/retrieve workflows, CI/CD
+13. **`integrations.md`** — External systems, callout patterns
+14. **`debugging-notes.md`** — Debug techniques, log levels
+15. **`known-issues.md`** — Platform bugs, workarounds
+
+---
+
+## 2. Auto-Update Protocol (MANDATORY)
+
+You MUST keep `current-state.md` and `inventory.md` updated as you work. These files are the project's living memory — they ensure continuity across sessions and agents.
+
+### When to Update `current-state.md`
+
+| Trigger | What to Update |
+|---------|---------------|
+| **Session start** | Add entry to `## Session Log` with date, agent, goal |
+| **Starting a task** | Move item to `In Progress` in `## Active Work`, mark `[/]` |
+| **Completing a task** | Move item to `Recently Completed`, mark `[x]`, note files changed |
+| **Hitting a blocker** | Add to `## Blockers` with impact and context |
+| **Resolving a blocker** | Remove from `## Blockers`, note resolution in session log |
+| **Making a design decision** | Add to `## Decisions` with rationale |
+| **Discovering an issue** | Add to `## Blockers` or update `known-issues.md` |
+| **Changing files** | Append to `## Files Changed This Session` |
+| **Session end** | Write summary in session log, update status |
+
+### When to Update `inventory.md`
+
+| Trigger | What to Update |
+|---------|---------------|
+| **First session on project** | Run populate commands, fill all sections |
+| **Creating a new class** | Add to the appropriate layer section (Service, Selector, etc.) |
+| **Creating a new LWC** | Add to LWC Components section |
+| **Creating a new Flow** | Add to Flows section |
+| **Creating a new object/field** | Add to Custom Objects section |
+| **Deleting anything** | Remove from inventory |
+
+### How to Update
+
+- **Method A (Recommended):** Use the helper script `.ai/scripts/update_state.py`. This ensures perfect formatting and saves time:
+  - `python3 .ai/scripts/update_state.py scan` (scans project and updates `inventory.md` automatically)
+  - `python3 .ai/scripts/update_state.py session-start --agent "AgentName" --goal "Goal description"`
+  - `python3 .ai/scripts/update_state.py task-start "Task description"`
+  - `python3 .ai/scripts/update_state.py task-complete "Task description" --files "comma,separated,files"`
+  - `python3 .ai/scripts/update_state.py session-end --summary "Summary of work" --files "comma,separated,files"`
+- **Method B (Manual):** If the script is unavailable or you have no command execution capabilities, edit the files manually using file replacement tools. Follow the format guidelines:
+  - Keep entries concise — one line per item.
+  - Use ISO dates: `2026-05-22`
+  - Use status emojis: 🟢 On Track, 🟡 At Risk, 🔴 Blocked, ✅ Done
+  - Prepend new entries (newest first) in the session log.
+
+### Example Session Log Entry
+
+```markdown
+### 2026-05-22 | Claude | Implement Account dedup service
+- ✅ Created `AccountSelector.findDuplicates()` with fuzzy matching
+- ✅ Created `AccountDedupService` with merge logic
+- ✅ Test class with 200+ records, 94% coverage
+- 🟡 Open question: Should we auto-merge or flag for review?
+- **Files:** AccountSelector.cls, AccountDedupService.cls, AccountDedupServiceTest.cls
+```
+
+---
+
+## 3. Anti-Hallucination Rules (NON-NEGOTIABLE)
+
+> **NEVER GUESS. ALWAYS VERIFY.**
+> Hallucinated field names, fake API methods, and invented CLI flags are the #1 cause of broken Salesforce code from AI agents.
+
+### The Verification Mandate
+
+Before writing code that references ANY of the following, you MUST verify it exists:
+
+| What | How to Verify |
+|------|--------------|
+| **Custom field** (`*__c`) | Check `inventory.md` → or run `FieldDefinition` SOQL (see `source-of-truth.md`) |
+| **Custom object** (`*__c`) | Check `inventory.md` → or run `EntityDefinition` SOQL |
+| **Apex class** | Check `inventory.md` → or `ls force-app/main/default/classes/` |
+| **LWC component** | Check `inventory.md` → or `ls force-app/main/default/lwc/` |
+| **Named Credential** | Check `inventory.md` → or query `NamedCredential` via Tooling API |
+| **Custom Label** | Check `inventory.md` → or query `ExternalString` via Tooling API |
+| **Custom Metadata** | Check `inventory.md` → or query the CMDT object directly |
+| **Standard Apex method** | Check `source-of-truth.md` standard library table |
+| **CLI flag** | Run the command with `--help` first |
+| **Governor limit number** | Check `org-context.local.md` (or `org-context.md`) — don't guess the numbers |
+
+### Verification Workflow
+
+```
+About to reference something?
+    │
+    ├── Is it in inventory.md?
+    │     ├── YES → Safe to use ✅
+    │     └── NO ──→ Can you verify it?
+    │                  ├── YES (run CLI/SOQL/ls) → Verify, then use ✅
+    │                  │                            Update inventory.md
+    │                  └── NO (no org access) → Flag it ⚠️
+    │                                           Tell the user:
+    │                                           "⚠️ Assumed: X exists — please verify"
+    │
+    └── Is it a standard Apex class/method?
+          ├── In source-of-truth.md table? → Safe to use ✅
+          └── Not in table? → Don't invent it ❌
+                               Search documentation or ask the user
+```
+
+### Confidence Signals (REQUIRED)
+
+When referencing Salesforce metadata in your response, prefix with:
+
+| Signal | Meaning | When to Use |
+|--------|---------|-------------|
+| ✅ **Verified** | Confirmed it exists via query, file check, or inventory | You checked and it's real |
+| ⚠️ **Assumed** | Reasonable assumption, not verified | You think it exists but didn't check |
+| ❓ **Uncertain** | You don't know — ask the developer | Don't fake it |
+
+**Example in code comments:**
+```apex
+// ✅ Verified: Account.Industry (standard field)
+// ⚠️ Assumed: Account.Health_Score__c — listed in architecture.md but not verified in org
+// ❓ Uncertain: Account.Risk_Rating__c — need to confirm this field exists
+```
+
+### Absolute Don'ts
+
+- ❌ **NEVER invent a field name** — If you're not sure `MyObject__c.MyField__c` exists, say so
+- ❌ **NEVER fabricate an Apex method** — If `Database.upsertImmediate()` isn't in the standard library table, it doesn't exist
+- ❌ **NEVER guess a CLI flag** — Run `--help` first
+- ❌ **NEVER assume org features** — Check `org-context.local.md` (or `org-context.md` if local does not exist) for enabled features
+- ❌ **NEVER make up governor limit numbers** — Reference `org-context.local.md` (or `org-context.md` if local does not exist)
+- ❌ **NEVER invent trigger events** — `before undelete` does not exist
+
+### When in Doubt
+
+Say this instead of guessing:
+
+> "I'm referencing `Account.Health_Score__c` based on the architecture doc, but I haven't verified this field exists in the org. Please confirm before deploying, or I can run a Tooling API query to check."
+
+---
+
+## 4. Next-Session Handoff Protocol
+
+At end of every session, update `current-state.md` → `## Next Session` section with:
+
+1. **What to do first** — The single most important task for the next agent
+2. **Context needed** — Files, decisions, or blockers the next agent must know
+3. **What NOT to do** — Anything that's blocked, waiting on human input, or risky
+
+This replaces the need for a separate `next-session.md` file.
+
+## 5. Context Snapshot Protocol
+
+At the end of long sessions or before a major context switch:
+
+1. Copy `context-snapshots/TEMPLATE.md` → `context-snapshots/YYYY-MM-DD.md`
+2. Fill in what was done, what's next, and key decisions
+3. This preserves deep context that `current-state.md` summarizes
+
+---
+
+## 6. Code Generation Rules
+
+Before generating ANY Salesforce code:
+
+1. **Check `inventory.md`** — Does the class/object/field you're referencing actually exist?
+2. **Check `source-of-truth.md`** — Are the Apex methods you're using real?
+3. Read the relevant `prompts/*.md` file for the code type
+4. Follow `conventions.md` — especially:
+   - `with sharing` on every class
+   - `WITH USER_MODE` on every SOQL query
+   - No SOQL/DML in loops
+   - One trigger per object → Handler → Service → Selector
+5. After generating code:
+   - Update `current-state.md` with files changed
+   - Update `inventory.md` with new classes/components created
+
+---
+
+## 7. Performance Rules
+
+Before writing code that processes data:
+
+1. **Check `performance.md`** — Know governor limits for the operation type
+2. **Choose the right async pattern** — See the selection table in `performance.md`
+3. **For 50K+ records** — Use Batch Apex, not collections in memory
+4. **For CPU-heavy logic** — Use Map lookups, not nested loops
+5. **Monitor in code** — Add `Limits.getQueries()` / `Limits.getCpuTime()` checks for critical methods
+
+---
+
+## 8. Pre-Deploy Self-Check
+
+Before telling the user code is ready to deploy:
+
+- [ ] All referenced fields/objects verified (via `inventory.md` or Tooling API)
+- [ ] All Apex methods used are from the standard library (no invented methods)
+- [ ] All classes use `with sharing`
+- [ ] All SOQL uses `WITH USER_MODE`
+- [ ] No SOQL or DML inside loops
+- [ ] Handles 200+ records (bulkified)
+- [ ] Error handling with meaningful messages (no empty catches)
+- [ ] No hardcoded IDs or credentials
+- [ ] Test coverage target ≥ 90% with meaningful assertions
+- [ ] `current-state.md` is updated with what was done
+- [ ] `inventory.md` is updated with any new metadata created
+- [ ] All assumptions flagged with ⚠️ for human review