sf-forcekit 1.0.0

package/templates/ai-dir/current-state.md

@@ -0,0 +1,113 @@
+# Current State
+
+> 🤖 **AUTO-UPDATED BY AI AGENTS** — This file is the project's living memory.
+> Agents MUST update this file as they work (see `rules.md` for protocol).
+> Humans: review periodically, correct if needed.
+
+---
+
+## Project Status
+
+**Last Updated:** 2026-05-22
+**Sprint/Phase:** [Update with current sprint]
+**Overall Status:** 🟢 On Track
+
+---
+
+## Active Work
+
+### In Progress
+
+
+### Upcoming
+
+
+### Recently Completed
+
+
+---
+
+## Blockers
+
+| Blocker | Impact | Severity | Added |
+|---------|--------|----------|-------|
+| _None_ | | | |
+
+---
+
+## Decisions
+
+| Date | Decision | Rationale |
+|------|----------|-----------|
+| | | |
+
+---
+
+## Files Changed This Session
+
+| File | Action | Notes |
+|------|--------|-------|
+| | | |
+
+---
+
+## Environment State
+
+| Environment | Last Deploy | Status | Notes |
+|-------------|-----------|--------|-------|
+| Dev Sandbox | — | 🟢 | |
+| QA Sandbox | — | 🟢 | |
+| UAT Sandbox | — | 🟢 | |
+| Production | — | 🟢 | |
+
+---
+
+## Governor Limit Watch
+
+| Limit | Current Usage | Max | Risk |
+|-------|-------------|-----|------|
+| API Calls (Daily) | 0 | 15,000 | 🟢 |
+| Data Storage | 0 MB | 5 MB | 🟢 |
+| File Storage | 0 MB | 20 MB | 🟢 |
+
+---
+
+## Technical Debt
+
+<!-- Track tech debt items here. Move to known-issues.md if they become bugs. -->
+
+| Item | Priority | Effort | Added | Status |
+|------|----------|--------|-------|--------|
+| _None tracked yet_ | | | | |
+
+---
+
+## Session Log
+
+<!-- Agent: Prepend a new entry at the TOP of this section every session.
+     Use the format below. This is the project's history. NEVER delete old entries.
+
+### YYYY-MM-DD | Agent Name | Session Goal
+- ✅ What was completed
+- 🟡 What's partially done
+- ❌ What failed and why
+- 💡 Key insight or decision
+- **Files:** comma-separated list of files touched
+-->
+
+### [First session entry will appear here]
+
+_No sessions recorded yet. The AI agent will begin logging here automatically._
+
+---
+
+## Next Session
+
+<!-- Agent: Update this at the END of every session. The next agent reads this FIRST. -->
+
+| Field | Value |
+|-------|-------|
+| **What to do first** | _Not set_ |
+| **Context needed** | _Read current-state.md session log_ |
+| **What NOT to do** | _Nothing blocked_ |
+| **Key files to review** | _None_ |

package/templates/ai-dir/debugging-notes.md

@@ -0,0 +1,165 @@
+# Debugging Notes
+
+> Debugging techniques, tools, and log configurations for this Salesforce project.
+
+---
+
+## Debug Log Configuration
+
+### Setting Up Trace Flags
+
+```bash
+# Enable debug logging for your user (via CLI)
+sf apex tail log --target-org <target_org>
+
+# Get recent logs
+sf apex log list --target-org <target_org>
+
+# View a specific log
+sf apex log get --target-org <target_org> --log-id <logId>
+```
+
+### Recommended Log Levels
+
+| Category | Level | When |
+|----------|-------|------|
+| Apex Code | FINEST | Deep Apex debugging |
+| Apex Code | DEBUG | Standard development |
+| SOQL | INFO | Query performance |
+| Callout | FINER | Integration debugging |
+| Validation | INFO | Rule troubleshooting |
+| Workflow | FINER | Automation debugging |
+| System | DEBUG | General platform |
+| Visualforce | NONE | Unless debugging VF |
+
+### Log Level Presets
+
+**Standard Dev:**
+```
+ApexCode=DEBUG;ApexProfiling=INFO;Callout=INFO;Database=INFO;System=DEBUG;Validation=INFO;Workflow=INFO
+```
+
+**Deep Apex Debug:**
+```
+ApexCode=FINEST;ApexProfiling=FINE;Callout=FINER;Database=FINE;System=DEBUG;Validation=INFO;Workflow=INFO
+```
+
+**Integration Debug:**
+```
+ApexCode=DEBUG;Callout=FINEST;System=DEBUG;Database=INFO;Validation=NONE;Workflow=NONE
+```
+
+---
+
+## Debugging Techniques
+
+### 1. System.debug() with Structured Output
+
+```apex
+// ✅ Use log levels and structured output
+System.debug(LoggingLevel.INFO, '>>> AccountService.processAccounts');
+System.debug(LoggingLevel.DEBUG, 'Input size: ' + accounts.size());
+System.debug(LoggingLevel.FINE, 'Account IDs: ' + JSON.serialize(accountIds));
+
+// ❌ Avoid bare debug statements
+System.debug(accounts); // Hard to find in logs
+```
+
+### 2. Apex Replay Debugger (VS Code)
+
+1. Set up trace flags for your user
+2. Reproduce the issue
+3. Download the debug log
+4. Open in VS Code → "SFDX: Launch Apex Replay Debugger"
+5. Set checkpoints (up to 5 active)
+6. Step through execution line by line
+
+### 3. Query Plan Tool
+
+```
+/services/data/v66.0/query?explain=SELECT+Id+FROM+Account+WHERE+Name='Test'
+```
+- Check in Developer Console → Query Plan
+- Look for `TableScan` (bad) vs `Index` (good)
+
+### 4. Limits Checking in Code
+
+```apex
+System.debug('SOQL queries used: ' + Limits.getQueries() + '/' + Limits.getLimitQueries());
+System.debug('DML statements used: ' + Limits.getDmlStatements() + '/' + Limits.getLimitDmlStatements());
+System.debug('CPU time used: ' + Limits.getCpuTime() + 'ms / ' + Limits.getLimitCpuTime() + 'ms');
+System.debug('Heap used: ' + Limits.getHeapSize() + ' / ' + Limits.getLimitHeapSize());
+```
+
+### 5. Anonymous Apex for Quick Testing
+
+```bash
+# Run anonymous Apex
+sf apex run --target-org <target_org> --file scripts/apex/debug-script.apex
+
+# Or inline
+echo "System.debug(UserInfo.getUserName());" | sf apex run --target-org <target_org>
+```
+
+---
+
+## Common Issues & Solutions
+
+### Governor Limit Errors
+
+| Error | Cause | Fix |
+|-------|-------|-----|
+| `Too many SOQL queries: 101` | SOQL in loop | Move query outside loop, use Map pattern |
+| `Too many DML statements: 151` | DML in loop | Collect records, single DML outside loop |
+| `CPU time limit exceeded` | Complex logic in loop | Optimize algorithms, use async |
+| `Heap size exceeded` | Large collections | Process in batches, use `Database.QueryLocator` |
+| `Too many callouts: 101` | Callouts in loop | Batch callouts, use Queueable chaining |
+
+### Mixed DML Errors
+
+```apex
+// ❌ This fails — User and custom object in same transaction
+insert new User(...);
+insert new Account(...);
+
+// ✅ Fix — Use @future or Queueable for the User DML
+@future
+public static void createUser(String email) {
+    insert new User(Email = email, ...);
+}
+```
+
+### UNABLE_TO_LOCK_ROW
+
+- Use `FOR UPDATE` in SOQL sparingly
+- Process parent records before children
+- Reduce transaction size
+- Add retry logic with Queueable
+
+---
+
+## Monitoring Tools
+
+| Tool | Purpose | Access |
+|------|---------|--------|
+| Debug Logs | Apex execution traces | Setup → Debug Logs |
+| Event Monitoring | Login, API, Report events | Shield add-on |
+| Apex Replay Debugger | Step-through debugging | VS Code extension |
+| Developer Console | Quick SOQL, logs, testing | /s/_ui/ForceQueryPage |
+| Query Plan | SOQL performance analysis | Developer Console |
+| `sf apex tail log` | Real-time log streaming | CLI |
+
+---
+
+## Project-Specific Debug Notes
+
+<!-- Add recurring issues and their solutions specific to this project -->
+
+```
+<!-- Example:
+- Account trigger: Watch for recursion when AccountService updates related Contacts
+  which re-fires the Contact trigger. Use static recursion guard.
+- Integration with ERP: Token expires every 60 min. Check Named Credential
+  refresh settings if callouts fail with 401.
+-->
+```

package/templates/ai-dir/deployment.md

@@ -0,0 +1,161 @@
+# Deployment
+
+> Deploy/retrieve workflows, CI/CD configuration, and release processes.
+
+---
+
+## Deployment Strategy
+
+**Method:** [Source Deploy (sf CLI) | DevOps Center | Change Sets | Unlocked Packages]
+**Source of Truth:** Git (`main` branch)
+**Branching Model:** [GitFlow | Trunk-Based | Feature Branches]
+
+---
+
+## CLI Deploy & Retrieve
+
+### Deploy to Org
+
+```bash
+# Full deploy from source
+sf project deploy start --target-org <target_org> --source-dir force-app
+
+# Deploy specific metadata
+sf project deploy start --target-org <target_org> --metadata "ApexClass:AccountService"
+
+# Deploy with test execution (required for Production)
+sf project deploy start --target-org <target_org> --source-dir force-app \
+  --test-level RunLocalTests
+
+# Dry run (validate only, no deploy)
+sf project deploy start --target-org <target_org> --source-dir force-app --dry-run
+
+# Check deploy status
+sf project deploy report --target-org <target_org>
+```
+
+### Retrieve from Org
+
+```bash
+# Retrieve specific metadata
+sf project retrieve start --target-org <target_org> --metadata "ApexClass:AccountService"
+
+# Retrieve by manifest
+sf project retrieve start --target-org <target_org> --manifest manifest/package.xml
+
+# Retrieve everything in project
+sf project retrieve start --target-org <target_org> --source-dir force-app
+```
+
+---
+
+## Test Levels
+
+| Level | When to Use | Command Flag |
+|-------|------------|-------------|
+| `NoTestRun` | Dev/sandbox only | `--test-level NoTestRun` |
+| `RunSpecifiedTests` | Known affected tests | `--test-level RunSpecifiedTests --tests AccountServiceTest` |
+| `RunLocalTests` | Production deploy (no packages) | `--test-level RunLocalTests` |
+| `RunAllTestsInOrg` | Full validation | `--test-level RunAllTestsInOrg` |
+
+---
+
+## CI/CD Pipeline
+
+### GitHub Actions (Template)
+
+```yaml
+# .github/workflows/sf-deploy.yml
+name: Salesforce Deploy
+
+on:
+  push:
+    branches: [main]
+    paths: ['force-app/**']
+  pull_request:
+    branches: [main]
+    paths: ['force-app/**']
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install SF CLI
+        run: npm install -g @salesforce/cli
+
+      - name: Authenticate
+        run: |
+          echo "${{ secrets.SF_AUTH_URL }}" > authfile.txt
+          sf org login sfdx-url --sfdx-url-file authfile.txt --alias ci-org
+
+      - name: Validate (PR) or Deploy (Push)
+        run: |
+          if [ "${{ github.event_name }}" == "pull_request" ]; then
+            sf project deploy start --target-org ci-org --source-dir force-app \
+              --dry-run --test-level RunLocalTests
+          else
+            sf project deploy start --target-org ci-org --source-dir force-app \
+              --test-level RunLocalTests
+          fi
+
+      - name: Run Tests
+        if: github.event_name == 'pull_request'
+        run: |
+          sf apex run test --target-org ci-org --code-coverage \
+            --result-format json --output-dir test-results
+
+      - name: Upload Test Results
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: test-results
+          path: test-results/
+```
+
+---
+
+## Pre-Deploy Checklist
+
+- [ ] All tests pass locally (`sf apex run test`)
+- [ ] Code coverage ≥ 75% (target 90%+)
+- [ ] No SOQL/DML in loops
+- [ ] Security enforced (CRUD/FLS/sharing)
+- [ ] No hardcoded IDs or credentials
+- [ ] Destructive changes handled separately
+- [ ] Dependent metadata deployed in correct order
+- [ ] Rollback plan documented for breaking changes
+
+---
+
+## Destructive Deployments
+
+```bash
+# Create destructiveChanges.xml in manifest/
+# Deploy with destructive changes
+sf project deploy start --target-org <target_org> \
+  --manifest manifest/package.xml \
+  --post-destructive-changes manifest/destructiveChanges.xml
+```
+
+---
+
+## Environment Promotion Path
+
+```
+Dev Sandbox → QA Sandbox → UAT Sandbox → Production
+     ↑                                        ↓
+   Feature branches ←── Hotfix branch ←── main branch
+```
+
+---
+
+## Rollback Procedures
+
+| Scenario | Action |
+|----------|--------|
+| Bad Apex deploy | Re-deploy previous version from git |
+| Bad Flow deploy | Deactivate Flow in Setup, deploy fixed version |
+| Bad field/object | Cannot easily rollback — test thoroughly in sandbox |
+| Data corruption | Restore from weekly export or Data Recovery service |

package/templates/ai-dir/integrations.md

@@ -0,0 +1,199 @@
+# Integrations
+
+> External systems, Named Credentials, callout patterns, and data sync strategies.
+
+---
+
+## Integration Inventory
+
+| System | Direction | Protocol | Auth Method | Named Credential | Frequency | Status |
+|--------|-----------|----------|-------------|-----------------|-----------|--------|
+| <!-- e.g., SAP ERP --> | Outbound | REST | OAuth 2.0 | `SAP_ERP_API` | Real-time | 🟢 Active |
+| <!-- Add rows --> | | | | | | |
+
+---
+
+## Integration Patterns
+
+### Outbound REST Callouts
+
+**Always use Named Credentials — never hardcode endpoints or credentials.**
+
+```apex
+public with sharing class ExternalApiService {
+
+    private static final String NAMED_CREDENTIAL = 'callout:External_API';
+
+    /**
+     * @description Makes an outbound REST call using Named Credentials.
+     * @param endpoint The API endpoint path (appended to Named Credential URL).
+     * @param method HTTP method (GET, POST, PUT, DELETE).
+     * @param body Request body (null for GET).
+     * @return Parsed response DTO.
+     */
+    public static ApiResponseDTO callExternalApi(String endpoint, String method, String body) {
+        HttpRequest req = new HttpRequest();
+        req.setEndpoint(NAMED_CREDENTIAL + endpoint);
+        req.setMethod(method);
+        req.setHeader('Content-Type', 'application/json');
+        req.setTimeout(10000); // 10 second timeout
+
+        if (body != null) {
+            req.setBody(body);
+        }
+
+        try {
+            HttpResponse res = new Http().send(req);
+
+            if (res.getStatusCode() >= 200 && res.getStatusCode() < 300) {
+                return (ApiResponseDTO) JSON.deserialize(res.getBody(), ApiResponseDTO.class);
+            } else {
+                throw new IntegrationException(
+                    'API call failed: ' + res.getStatusCode() + ' - ' + res.getBody()
+                );
+            }
+        } catch (CalloutException e) {
+            Logger.error('Callout to ' + endpoint + ' failed', e);
+            throw new IntegrationException('External service unavailable: ' + e.getMessage(), e);
+        }
+    }
+}
+```
+
+### Inbound REST API
+
+```apex
+@RestResource(urlMapping='/api/v1/accounts/*')
+global with sharing class AccountRestResource {
+
+    @HttpGet
+    global static AccountDTO getAccount() {
+        RestRequest req = RestContext.request;
+        String accountId = req.requestURI.substringAfterLast('/');
+
+        List<Account> accounts = AccountSelector.getByIds(new Set<Id>{accountId});
+        if (accounts.isEmpty()) {
+            RestContext.response.statusCode = 404;
+            return null;
+        }
+        return new AccountDTO(accounts[0]);
+    }
+
+    @HttpPost
+    global static AccountDTO createAccount(AccountDTO dto) {
+        try {
+            Account acc = AccountService.createFromDTO(dto);
+            RestContext.response.statusCode = 201;
+            return new AccountDTO(acc);
+        } catch (DmlException e) {
+            RestContext.response.statusCode = 400;
+            throw e;
+        }
+    }
+}
+```
+
+### Async Patterns
+
+| Pattern | Use When | Governor-Friendly |
+|---------|----------|-------------------|
+| **Queueable** | Complex types, chaining, < 50k records | ✅ Preferred |
+| **@future** | Simple, fire-and-forget | ⚠️ Limited (no complex types) |
+| **Batch Apex** | 50k+ records, long-running | ✅ QueryLocator = 50M rows |
+| **Platform Events** | Decoupled, cross-system, event-driven | ✅ Excellent |
+| **Scheduled Apex** | Time-based recurring jobs | ✅ Cron expressions |
+
+```apex
+// ✅ Preferred — Queueable with chaining
+public class SyncAccountsQueueable implements Queueable, Database.AllowsCallouts {
+
+    private List<Account> accounts;
+    private Integer retryCount;
+
+    public SyncAccountsQueueable(List<Account> accounts, Integer retryCount) {
+        this.accounts = accounts;
+        this.retryCount = retryCount;
+    }
+
+    public void execute(QueueableContext context) {
+        try {
+            ExternalApiService.syncAccounts(accounts);
+        } catch (IntegrationException e) {
+            if (retryCount < 3) {
+                System.enqueueJob(new SyncAccountsQueueable(accounts, retryCount + 1));
+            } else {
+                Logger.error('Max retries exceeded for account sync', e);
+            }
+        }
+    }
+}
+```
+
+### Platform Events
+
+```apex
+// Publishing
+EventBus.publish(new Order_Status_Change__e(
+    Order_Id__c = orderId,
+    New_Status__c = 'Shipped',
+    Changed_By__c = UserInfo.getUserId()
+));
+
+// Subscribing (Apex Trigger on Platform Event)
+trigger OrderStatusChangeTrigger on Order_Status_Change__e (after insert) {
+    OrderStatusChangeHandler.handle(Trigger.new);
+}
+```
+
+---
+
+## Named Credential Setup
+
+| Setting | Value |
+|---------|-------|
+| **Label** | [Human-readable name] |
+| **URL** | [Base API URL] |
+| **Auth Protocol** | OAuth 2.0 / Named Principal / Per User |
+| **Auth Provider** | [Custom Auth Provider if OAuth] |
+| **Certificate** | [If mTLS required] |
+
+### Checklist for New Integration
+
+- [ ] Named Credential created in target org
+- [ ] Auth Provider configured (if OAuth)
+- [ ] Remote Site Setting or CSP Trusted Site added (if not using Named Cred)
+- [ ] Callout timeout configured (default 10s, max 120s)
+- [ ] Error handling with retry logic
+- [ ] Logging for all callout responses
+- [ ] Unit tests with `HttpCalloutMock`
+- [ ] Bulk-safe (no callouts in loops)
+
+---
+
+## Data Sync Strategies
+
+| Strategy | Direction | Frequency | Tool |
+|----------|-----------|-----------|------|
+| Real-time push | Outbound | On record change | Trigger → Queueable → REST |
+| Real-time pull | Inbound | On demand | @RestResource |
+| Near real-time | Both | Minutes | Platform Events + CDC |
+| Batch sync | Both | Scheduled | Batch Apex + REST |
+| ETL | Inbound | Nightly | MuleSoft / Informatica / Jitterbit |
+
+---
+
+## Project-Specific Integrations
+
+<!-- Document each integration with details -->
+
+### [Integration Name]
+
+- **System:** 
+- **Direction:** Inbound / Outbound / Bidirectional
+- **Protocol:** REST / SOAP / Platform Event
+- **Named Credential:** `callout:___`
+- **Frequency:** Real-time / Batch / Scheduled
+- **Objects Involved:** 
+- **Error Handling:** 
+- **Monitoring:** 
+- **Owner:**