@salesforce/afv-skills 1.8.0 → 1.9.0

package/skills/handling-sf-data/references/cleanup-rollback-guide.md

@@ -0,0 +1,84 @@
+<!-- Parent: handling-sf-data/SKILL.md -->
+# Cleanup and Rollback Guide
+
+Strategies for test data isolation and cleanup.
+
+## Savepoint/Rollback Pattern
+
+Best for synchronous test isolation.
+
+```apex
+// Create savepoint BEFORE any DML
+Savepoint sp = Database.setSavepoint();
+
+try {
+    // Create test data
+    List<Account> accounts = TestDataFactory_Account.create(100);
+
+    // Run your tests
+    Test.startTest();
+    MyClass.processAccounts(accounts);
+    Test.stopTest();
+
+    // Assert results
+    System.assertEquals(expected, actual);
+
+} finally {
+    // Always rollback
+    Database.rollback(sp);
+}
+```
+
+**Limitations:**
+- Does not roll back async operations
+- Maximum 5 savepoints per transaction
+
+## Cleanup by Name Pattern
+
+```apex
+String pattern = 'Test%';
+
+DELETE [SELECT Id FROM Opportunity WHERE Name LIKE :pattern];
+DELETE [SELECT Id FROM Contact WHERE LastName LIKE :pattern];
+DELETE [SELECT Id FROM Account WHERE Name LIKE :pattern];
+```
+
+**Order matters:** Delete children before parents.
+
+## Cleanup by Date
+
+```apex
+DateTime startTime = DateTime.now().addHours(-1);
+
+DELETE [
+    SELECT Id FROM Account
+    WHERE CreatedDate >= :startTime
+    AND Name LIKE 'Test%'
+];
+```
+
+## Cleanup via sf CLI
+
+```bash
+# Export IDs to delete
+sf data query \
+  --query "SELECT Id FROM Account WHERE Name LIKE 'Test%'" \
+  --target-org myorg \
+  --result-format csv \
+  > delete.csv
+
+# Bulk delete
+sf data delete bulk \
+  --file delete.csv \
+  --sobject Account \
+  --target-org myorg \
+  --wait 30
+```
+
+## Best Practices
+
+1. **Track created IDs** - Store in Set<Id>
+2. **Delete in order** - Children first, parents last
+3. **Use test prefixes** - 'Test', 'BulkTest'
+4. **Preview before delete** - Verify records first
+5. **Use @isTest** - Auto-rollback in tests

package/skills/handling-sf-data/references/crud-workflow-example.md

@@ -0,0 +1,183 @@
+<!-- Parent: handling-sf-data/SKILL.md -->
+# CRUD Workflow Example
+
+Complete end-to-end example of data operations using handling-sf-data skill.
+
+## Scenario
+
+Create a Deal Desk workflow test environment with:
+- Accounts with varying revenue tiers
+- Contacts as decision makers
+- Opportunities at different stages
+
+## Phase 1: Discovery (sf-metadata)
+
+```
+Skill(skill="sf-metadata")
+Request: "Describe object Account in org dev - show required fields and picklist values"
+```
+
+**Response shows:**
+- Required: Name
+- Picklists: Industry, Type, Rating
+
+## Phase 2: Create Records
+
+### sf CLI - Single Record
+```bash
+sf data create record \
+  --sobject Account \
+  --values "Name='Enterprise Corp' Industry='Technology' AnnualRevenue=5000000" \
+  --target-org dev \
+  --json
+```
+
+**Output:**
+```json
+{
+  "status": 0,
+  "result": {
+    "id": "001XXXXXXXXXXXX",
+    "success": true
+  }
+}
+```
+
+### sf CLI - Query Created Record
+```bash
+sf data query \
+  --query "SELECT Id, Name, Industry, AnnualRevenue FROM Account WHERE Name = 'Enterprise Corp'" \
+  --target-org dev \
+  --json
+```
+
+## Phase 3: Update Records
+
+### Update Single Record
+```bash
+sf data update record \
+  --sobject Account \
+  --record-id 001XXXXXXXXXXXX \
+  --values "Rating='Hot' Type='Customer - Direct'" \
+  --target-org dev
+```
+
+### Verify Update
+```bash
+sf data get record \
+  --sobject Account \
+  --record-id 001XXXXXXXXXXXX \
+  --target-org dev
+```
+
+## Phase 4: Create Related Records
+
+### Create Contact for Account
+```bash
+sf data create record \
+  --sobject Contact \
+  --values "FirstName='John' LastName='Smith' AccountId='001XXXXXXXXXXXX' Title='CTO'" \
+  --target-org dev
+```
+
+### Create Opportunity
+```bash
+sf data create record \
+  --sobject Opportunity \
+  --values "Name='Enterprise Deal' AccountId='001XXXXXXXXXXXX' StageName='Prospecting' CloseDate=2025-03-31 Amount=250000" \
+  --target-org dev
+```
+
+## Phase 5: Query Relationships
+
+### Parent-to-Child (Subquery)
+```bash
+sf data query \
+  --query "SELECT Id, Name, (SELECT Id, Name, Title FROM Contacts), (SELECT Id, Name, Amount, StageName FROM Opportunities) FROM Account WHERE Name = 'Enterprise Corp'" \
+  --target-org dev \
+  --json
+```
+
+### Child-to-Parent (Dot Notation)
+```bash
+sf data query \
+  --query "SELECT Id, Name, Account.Name, Account.Industry FROM Contact WHERE Account.Name = 'Enterprise Corp'" \
+  --target-org dev
+```
+
+## Phase 6: Delete Records
+
+### Delete in Correct Order
+Children first, then parents:
+
+```bash
+# Delete Opportunities
+sf data delete record \
+  --sobject Opportunity \
+  --record-id 006XXXXXXXXXXXX \
+  --target-org dev
+
+# Delete Contacts
+sf data delete record \
+  --sobject Contact \
+  --record-id 003XXXXXXXXXXXX \
+  --target-org dev
+
+# Delete Account
+sf data delete record \
+  --sobject Account \
+  --record-id 001XXXXXXXXXXXX \
+  --target-org dev
+```
+
+## Anonymous Apex Alternative
+
+For complex operations, use Anonymous Apex:
+
+```apex
+// Create complete hierarchy in one transaction
+Account acc = new Account(
+    Name = 'Enterprise Corp',
+    Industry = 'Technology',
+    AnnualRevenue = 5000000
+);
+insert acc;
+
+Contact con = new Contact(
+    FirstName = 'John',
+    LastName = 'Smith',
+    AccountId = acc.Id,
+    Title = 'CTO'
+);
+insert con;
+
+Opportunity opp = new Opportunity(
+    Name = 'Enterprise Deal',
+    AccountId = acc.Id,
+    ContactId = con.Id,
+    StageName = 'Prospecting',
+    CloseDate = Date.today().addDays(90),
+    Amount = 250000
+);
+insert opp;
+
+System.debug('Created hierarchy: Account=' + acc.Id + ', Contact=' + con.Id + ', Opp=' + opp.Id);
+```
+
+Execute:
+```bash
+sf apex run --file create-hierarchy.apex --target-org dev
+```
+
+## Validation Score
+
+```
+Score: 125/130 ⭐⭐⭐⭐⭐ Excellent
+├─ Query Efficiency: 25/25 (indexed fields, no N+1)
+├─ Bulk Safety: 23/25 (single records OK for demo)
+├─ Data Integrity: 20/20 (all required fields)
+├─ Security & FLS: 20/20 (no PII exposed)
+├─ Test Patterns: 12/15 (single record demo)
+├─ Cleanup & Isolation: 15/15 (proper delete order)
+└─ Documentation: 10/10 (fully documented)
+```

package/skills/handling-sf-data/references/governor-limits-reference.md

@@ -0,0 +1,74 @@
+<!-- Parent: handling-sf-data/SKILL.md -->
+# Governor Limits Reference
+
+Essential limits for Salesforce data operations.
+
+## SOQL Limits
+
+| Limit | Synchronous | Asynchronous |
+|-------|-------------|--------------|
+| Total queries | 100 | 200 |
+| Rows retrieved | 50,000 | 50,000 |
+| QueryLocator rows | N/A | 50,000,000 |
+| Query timeout | 120 seconds | 120 seconds |
+
+## DML Limits
+
+| Limit | Synchronous | Asynchronous |
+|-------|-------------|--------------|
+| DML statements | 150 | 150 |
+| Rows processed | 10,000 | 10,000 |
+
+## CPU and Memory
+
+| Limit | Synchronous | Asynchronous |
+|-------|-------------|--------------|
+| CPU time | 10,000 ms | 60,000 ms |
+| Heap size | 6 MB | 12 MB |
+
+## Bulk API Limits
+
+| Limit | Value |
+|-------|-------|
+| Batches per 24 hours | 10,000 |
+| Records per 24 hours | 10,000,000 |
+| Max file size | 100 MB |
+| Concurrent jobs | 100 |
+
+## Staying Within Limits
+
+### SOQL Best Practices
+```apex
+// BAD: Query in loop
+for (Account acc : accounts) {
+    List<Contact> cons = [SELECT Id FROM Contact WHERE AccountId = :acc.Id];  // ❌
+}
+
+// GOOD: Single query with relationship
+List<Account> accs = [
+    SELECT Id, (SELECT Id FROM Contacts)
+    FROM Account
+    WHERE Id IN :accountIds
+];  // ✓
+```
+
+### DML Best Practices
+```apex
+// BAD: DML in loop
+for (Account acc : accounts) {
+    update acc;  // ❌
+}
+
+// GOOD: Bulk DML
+update accounts;  // ✓
+```
+
+## Monitoring Limits
+
+```apex
+System.debug('SOQL Queries: ' + Limits.getQueries() + '/' + Limits.getLimitQueries());
+System.debug('DML Statements: ' + Limits.getDmlStatements() + '/' + Limits.getLimitDmlStatements());
+System.debug('DML Rows: ' + Limits.getDmlRows() + '/' + Limits.getLimitDmlRows());
+System.debug('CPU Time: ' + Limits.getCpuTime() + '/' + Limits.getLimitCpuTime());
+System.debug('Heap Size: ' + Limits.getHeapSize() + '/' + Limits.getLimitHeapSize());
+```

package/skills/handling-sf-data/references/orchestration.md

@@ -0,0 +1,174 @@
+<!-- Parent: handling-sf-data/SKILL.md -->
+# Multi-Skill Orchestration: handling-sf-data Perspective
+
+This document details how handling-sf-data fits into the multi-skill workflow for Salesforce development.
+
+---
+
+## Standard Orchestration Order
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│  STANDARD MULTI-SKILL ORCHESTRATION ORDER                                   │
+├─────────────────────────────────────────────────────────────────────────────┤
+│  1. sf-metadata                                                             │
+│     └── Create object/field definitions (LOCAL files)                       │
+│                                                                             │
+│  2. sf-flow                                                                 │
+│     └── Create flow definitions (LOCAL files)                               │
+│                                                                             │
+│  3. deploying-metadata                                                               │
+│     └── Deploy all metadata (REMOTE)                                        │
+│                                                                             │
+│  4. handling-sf-data  ◀── YOU ARE HERE (LAST!)                                      │
+│     └── Create test data (REMOTE - objects must exist!)                     │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## ⚠️ Why handling-sf-data Goes LAST
+
+**handling-sf-data operates on REMOTE org data.** Objects/fields must be deployed before handling-sf-data can:
+- Insert records
+- Query existing data
+- Run test factories
+- Generate bulk test data
+
+```
+ERROR: "SObject type 'Quote__c' is not supported"
+CAUSE: Quote__c object was never deployed to the org
+FIX:   Run deploying-metadata BEFORE handling-sf-data
+```
+
+---
+
+## Common Errors from Wrong Order
+
+| Error | Cause | Fix |
+|-------|-------|-----|
+| `SObject type 'X' not supported` | Object not deployed | Deploy via deploying-metadata first |
+| `INVALID_FIELD: No such column 'Field__c'` | Field not deployed OR FLS | Deploy field + Permission Set |
+| `REQUIRED_FIELD_MISSING` | Validation rule requires field | Include all required fields |
+| `FIELD_CUSTOM_VALIDATION_EXCEPTION` | Validation rule triggered | Use valid test data values |
+
+---
+
+## Test Data After Triggers/Flows
+
+When testing triggers or flows, always create test data AFTER deployment:
+
+```
+1. sf-apex   → Create trigger handler class
+2. sf-flow   → Create record-triggered flow
+3. deploying-metadata → Deploy trigger + flow + objects
+4. handling-sf-data   ◀── CREATE TEST DATA NOW
+              └── Triggers and flows will fire!
+```
+
+**Why?** Test data insertion triggers flows/triggers. If those aren't deployed, you're not testing realistic behavior.
+
+---
+
+## The 251-Record Pattern
+
+Always test with **251 records** to cross the 200-record batch boundary:
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│  BATCH BOUNDARY TESTING                                                     │
+├─────────────────────────────────────────────────────────────────────────────┤
+│  Records 1-200:    First batch                                              │
+│  Records 201-251:  Second batch (crosses boundary!)                         │
+│                                                                             │
+│  Tests: N+1 queries, bulkification, governor limits                         │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+**Command:**
+```bash
+sf apex run --file test-factory.apex --target-org alias
+# test-factory.apex creates 251 records
+```
+
+---
+
+## Cross-Skill Integration Table
+
+| From Skill | To handling-sf-data | When |
+|------------|------------|------|
+| sf-apex | → handling-sf-data | "Create 251 Accounts for bulk testing" |
+| sf-flow | → handling-sf-data | "Create Opportunities with StageName='Closed Won'" |
+| running-apex-tests | → handling-sf-data | "Generate test records for test class" |
+
+| From handling-sf-data | To Skill | When |
+|--------------|----------|------|
+| handling-sf-data | → sf-metadata | "Describe Invoice__c" (discover object structure) |
+| handling-sf-data | → deploying-metadata | "Redeploy field after adding validation rule" |
+
+---
+
+## Prerequisites Check
+
+Before using handling-sf-data, verify:
+
+```bash
+# Check org connection
+sf org display --target-org alias
+
+# Check objects exist
+sf sobject describe --sobject MyObject__c --target-org alias --json
+
+# Check field-level security (if field not visible)
+sf data query --query "SELECT Id FROM FieldPermissions WHERE SobjectType='MyObject__c'" --use-tooling-api --target-org alias
+```
+
+---
+
+## Factory Pattern Integration
+
+Test Data Factory classes work with handling-sf-data:
+
+```
+sf-apex:  Creates TestDataFactory_Account.cls
+          ↓
+deploying-metadata: Deploys factory class
+          ↓
+handling-sf-data:  Calls factory via Anonymous Apex
+          ↓
+          251 records created → triggers fire → flows run
+```
+
+**Anonymous Apex:**
+```apex
+List<Account> accounts = TestDataFactory_Account.create(251);
+System.debug('Created ' + accounts.size() + ' accounts');
+```
+
+---
+
+## Cleanup Sequence
+
+After testing, clean up in reverse order:
+
+```
+1. handling-sf-data   → Delete test records
+2. deploying-metadata → Deactivate flows (if needed)
+3. deploying-metadata → Remove test metadata (if needed)
+```
+
+**Cleanup command:**
+```bash
+sf apex run --file cleanup.apex --target-org alias
+# cleanup.apex: DELETE [SELECT Id FROM Account WHERE Name LIKE 'Test%']
+```
+
+---
+
+## Related Documentation
+
+| Topic | Location |
+|-------|----------|
+| Test data patterns | `handling-sf-data/references/test-data-patterns.md` |
+| Cleanup guide | `handling-sf-data/references/cleanup-rollback-guide.md` |
+| Factory templates | `handling-sf-data/assets/factories/` |