sf-forcekit 1.0.0

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

@@ -0,0 +1,125 @@
+# Flow Building Rules
+
+> Instructions for AI agents when designing or reviewing Salesforce Flows.
+
+---
+
+## Core Rules
+
+| Rule | Details |
+|------|---------|
+| **Prefer Record-Triggered Flows** | Over Process Builder (deprecated) and Workflow Rules |
+| **Before-Save for field updates** | No DML consumed — free performance |
+| **After-Save for related records** | Only when you need DML on other objects or platform events |
+| **Fault paths on EVERY DML/callout** | No silent failures |
+| **No hardcoded IDs** | Use Custom Labels or Custom Metadata Types |
+| **No hardcoded strings** | Use Custom Labels for user-facing text |
+
+---
+
+## Flow Naming Convention
+
+```
+{Object}_{TriggerTiming}_{Purpose}
+
+Examples:
+  Account_BeforeSave_DefaultIndustry
+  Contact_AfterSave_SyncToExternalSystem
+  Opportunity_BeforeSave_ValidateAmount
+  Case_AfterSave_NotifyTeam
+  Lead_Scheduled_CleanupStale
+```
+
+For non-record-triggered flows:
+```
+{Purpose}_{Type}
+
+Examples:
+  OrderApproval_ScreenFlow
+  DataMigration_AutolaunchedFlow
+  WeeklyReport_ScheduledFlow
+```
+
+---
+
+## Before-Save vs After-Save Decision Tree
+
+```
+Need to update ONLY the triggering record's fields?
+  → YES → Before-Save Flow (no DML cost)
+  → NO  → Do you need to:
+           • Create/update RELATED records? → After-Save Flow
+           • Send emails? → After-Save Flow
+           • Publish Platform Events? → After-Save Flow
+           • Make callouts? → After-Save Flow (+ Asynchronous path)
+```
+
+---
+
+## Mandatory Elements
+
+### 1. Fault Paths
+
+Every DML element (Create, Update, Delete) and every Action element (Callout, Invocable) MUST have a fault connector.
+
+```
+[Create Records] ──success──→ [Next Element]
+       │
+       └──fault──→ [Log Error] → [Notify Admin]
+```
+
+### 2. Entry Conditions
+
+- Be specific with entry conditions to avoid unnecessary executions
+- Use `$Record.FieldName` for current values
+- Use `$Record__Prior.FieldName` for before-update comparisons
+- Filter with `AND`/`OR` to narrow scope
+
+### 3. Bulkification
+
+Flows are auto-bulkified for DML, but:
+- Avoid **Get Records** inside loops (SOQL in loop equivalent)
+- Use **Collection Variables** and **Assignment** elements for batch operations
+- Pre-fetch related data before loops
+
+---
+
+## Anti-Patterns (Avoid These)
+
+| Anti-Pattern | Why It's Bad | Fix |
+|-------------|-------------|-----|
+| Get Records inside a Loop | SOQL in loop — hits governor limits | Pre-fetch outside loop into Collection Variable |
+| Hardcoded Record Type IDs | Breaks across environments | Use `$Label.RecordTypeName` or CMDT |
+| No fault paths | Silent failures, no debugging | Add fault connector to every DML/callout |
+| After-Save for field updates | Wastes DML, causes recursion | Use Before-Save instead |
+| Overly broad entry conditions | Runs on every update, burns CPU | Narrow with field change conditions |
+
+---
+
+## Flow Testing Checklist
+
+- [ ] Test with single record
+- [ ] Test with bulk records (verify no governor limit issues)
+- [ ] Test fault paths (what happens on DML error?)
+- [ ] Test with different user profiles (sharing/FLS)
+- [ ] Verify no recursion (update on same object doesn't re-trigger infinitely)
+- [ ] Test entry conditions (verify flow doesn't fire when it shouldn't)
+- [ ] Validate in sandbox before production
+
+---
+
+## Flow Documentation Template
+
+When creating or reviewing a flow, document:
+
+```markdown
+### Flow: {Flow_Name}
+- **Object:** {Object API Name}
+- **Type:** Record-Triggered (Before/After Save) | Screen | Autolaunched | Scheduled
+- **Entry Conditions:** {Describe when this flow fires}
+- **Purpose:** {What this flow does}
+- **DML Operations:** {List any create/update/delete}
+- **Callouts:** {Any external callouts}
+- **Platform Events:** {Any events published}
+- **Error Handling:** {Fault path behavior}
+```

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

@@ -0,0 +1,230 @@
+# LWC Generation Rules
+
+> Instructions for AI agents when generating Lightning Web Components.
+
+---
+
+## Before Writing Any LWC
+
+1. **Check `conventions.md`** for naming and styling rules.
+2. **Check `architecture.md`** for existing components and patterns.
+3. **Determine data strategy**: Wire Service → LDS → GraphQL → Imperative Apex (in order of preference).
+
+---
+
+## Component Structure
+
+Every LWC must have this file structure:
+
+```
+lwc/
+  componentName/              ← camelCase, always
+    componentName.html        ← Template
+    componentName.js          ← Controller
+    componentName.css         ← Styles (no inline styles)
+    componentName.js-meta.xml ← Metadata config
+    __tests__/                ← Jest tests
+      componentName.test.js
+```
+
+---
+
+## Mandatory Patterns
+
+### 1. Three-State Template (Loading, Error, Data)
+
+```html
+<template>
+    <!-- Loading State -->
+    <template if:true={isLoading}>
+        <lightning-spinner
+            alternative-text="Loading"
+            size="medium">
+        </lightning-spinner>
+    </template>
+
+    <!-- Error State -->
+    <template if:true={hasError}>
+        <div class="slds-illustration slds-illustration_small">
+            <p class="slds-text-body_regular slds-text-color_error">
+                {errorMessage}
+            </p>
+            <lightning-button
+                label="Retry"
+                variant="brand"
+                onclick={handleRetry}>
+            </lightning-button>
+        </div>
+    </template>
+
+    <!-- Data State -->
+    <template if:true={hasData}>
+        <!-- Component content here -->
+    </template>
+
+    <!-- Empty State -->
+    <template if:false={hasData}>
+        <template if:false={isLoading}>
+            <template if:false={hasError}>
+                <div class="slds-align_absolute-center slds-p-around_medium">
+                    <p class="slds-text-body_regular slds-text-color_weak">
+                        No records found.
+                    </p>
+                </div>
+            </template>
+        </template>
+    </template>
+</template>
+```
+
+### 2. Wire Service (Default for Data)
+
+```javascript
+import { LightningElement, api, wire } from 'lwc';
+import getAccounts from '@salesforce/apex/AccountController.getAccounts';
+
+export default class AccountList extends LightningElement {
+    @api recordId;
+
+    @wire(getAccounts, { accountId: '$recordId' })
+    wiredAccounts;
+
+    get isLoading() {
+        return !this.wiredAccounts.data && !this.wiredAccounts.error;
+    }
+
+    get hasError() {
+        return !!this.wiredAccounts.error;
+    }
+
+    get hasData() {
+        return this.wiredAccounts.data && this.wiredAccounts.data.length > 0;
+    }
+
+    get errorMessage() {
+        return this.wiredAccounts.error?.body?.message || 'An error occurred';
+    }
+
+    get accounts() {
+        return this.wiredAccounts.data || [];
+    }
+}
+```
+
+### 3. Imperative Apex (Only When Wire Won't Work)
+
+```javascript
+import { LightningElement, api } from 'lwc';
+import processRecords from '@salesforce/apex/RecordService.processRecords';
+import { ShowToastEvent } from 'lightning/platformShowToastEvent';
+
+export default class RecordProcessor extends LightningElement {
+    @api recordId;
+    isProcessing = false;
+
+    async handleProcess() {
+        this.isProcessing = true;
+        try {
+            const result = await processRecords({ recordId: this.recordId });
+            this.dispatchEvent(new ShowToastEvent({
+                title: 'Success',
+                message: result.message,
+                variant: 'success'
+            }));
+        } catch (error) {
+            this.dispatchEvent(new ShowToastEvent({
+                title: 'Error',
+                message: error.body?.message || 'Processing failed',
+                variant: 'error'
+            }));
+        } finally {
+            this.isProcessing = false;
+        }
+    }
+}
+```
+
+### 4. CSS — No Inline Styles
+
+```css
+/* componentName.css */
+
+/* Use SLDS design tokens via custom properties */
+:host {
+    --card-spacing: var(--lwc-spacingMedium, 1rem);
+}
+
+.container {
+    padding: var(--card-spacing);
+}
+
+.highlight {
+    background-color: var(--lwc-colorBackgroundHighlight, #fffbe5);
+    border-radius: var(--lwc-borderRadiusMedium, 0.25rem);
+}
+
+/* ❌ NEVER do this in the template:
+   <div style="padding: 16px; color: red;"> */
+```
+
+### 5. Meta XML Config
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<LightningComponentBundle xmlns="http://soap.sforce.com/2006/04/metadata">
+    <apiVersion>66.0</apiVersion>
+    <isExposed>true</isExposed>
+    <targets>
+        <target>lightning__RecordPage</target>
+        <target>lightning__AppPage</target>
+        <target>lightning__HomePage</target>
+    </targets>
+    <targetConfigs>
+        <targetConfig targets="lightning__RecordPage">
+            <objects>
+                <object>Account</object>
+            </objects>
+            <property name="title" type="String" default="Account Summary" />
+        </targetConfig>
+    </targetConfigs>
+</LightningComponentBundle>
+```
+
+---
+
+## Event Communication
+
+| Pattern | When | Direction |
+|---------|------|-----------|
+| `CustomEvent` | Parent-child | Child → Parent |
+| `@api` property | Parent-child | Parent → Child |
+| Lightning Message Service (LMS) | Cross-component (unrelated) | Any → Any |
+| `pubsub` module | Legacy (avoid) | — |
+
+```javascript
+// Child: dispatch custom event
+this.dispatchEvent(new CustomEvent('recordselected', {
+    detail: { recordId: this.selectedId },
+    bubbles: false,   // Don't bubble by default
+    composed: false   // Don't cross shadow DOM by default
+}));
+
+// Parent: listen in template
+// <c-child-component onrecordselected={handleRecordSelected}></c-child-component>
+handleRecordSelected(event) {
+    const selectedId = event.detail.recordId;
+}
+```
+
+---
+
+## Checklist Before Returning LWC Code
+
+- [ ] camelCase component folder name
+- [ ] Handles loading, error, and empty states
+- [ ] Uses `@wire` (imperative only when necessary)
+- [ ] No inline styles — CSS in component `.css` file
+- [ ] Uses SLDS classes and design tokens
+- [ ] Meta XML has correct API version (66.0) and targets
+- [ ] Error messages displayed to user via toast or inline
+- [ ] Event names are lowercase with no hyphens

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

@@ -0,0 +1,181 @@
+# Security Rules
+
+> Instructions for AI agents on security enforcement, CRUD/FLS, sharing, and AppExchange review readiness.
+
+---
+
+## Non-Negotiable Security Rules
+
+### 1. CRUD / FLS Enforcement
+
+**Every SOQL query must enforce field-level security.**
+
+```apex
+// ✅ API v60.0+ — Use USER_MODE (preferred)
+List<Account> accounts = [
+    SELECT Id, Name, Industry
+    FROM Account
+    WHERE Id IN :ids
+    WITH USER_MODE
+];
+
+// ✅ API v48.0+ — Alternative
+List<Account> accounts = [
+    SELECT Id, Name, Industry
+    FROM Account
+    WHERE Id IN :ids
+    WITH SECURITY_ENFORCED
+];
+```
+
+**DML with FLS enforcement:**
+
+```apex
+// Strip inaccessible fields before DML
+SObjectAccessDecision decision = Security.stripInaccessible(
+    AccessType.CREATABLE, recordsToInsert
+);
+insert decision.getRecords();
+
+// Check which fields were stripped
+Map<String, Set<String>> removedFields = decision.getRemovedFields();
+if (!removedFields.isEmpty()) {
+    Logger.warn('Fields stripped due to FLS: ' + removedFields);
+}
+```
+
+### 2. Sharing Model
+
+```apex
+// ✅ DEFAULT — Always use with sharing
+public with sharing class AccountService { }
+
+// ⚠️ EXCEPTION — Only with documented justification
+// @reason: Needs cross-user visibility for admin batch job
+public without sharing class AdminBatchService { }
+
+// ❌ NEVER — Inherited sharing in new code
+public class SomeService { } // Sharing context is unpredictable
+```
+
+### 3. SOQL Injection Prevention
+
+```apex
+// ✅ CORRECT — Bind variables
+String searchTerm = '%' + String.escapeSingleQuotes(userInput) + '%';
+List<Account> results = [
+    SELECT Id, Name
+    FROM Account
+    WHERE Name LIKE :searchTerm
+    WITH USER_MODE
+];
+
+// ✅ For dynamic SOQL — Use Database.query with bind variables
+String query = 'SELECT Id, Name FROM Account WHERE Industry = :industry WITH USER_MODE';
+List<Account> results = Database.query(query);
+
+// ❌ NEVER — String concatenation in SOQL
+String query = 'SELECT Id FROM Account WHERE Name = \'' + userInput + '\''; // INJECTION!
+```
+
+### 4. XSS Prevention (LWC/Aura)
+
+```javascript
+// ✅ LWC automatically escapes template expressions
+// {accountName} in template is auto-escaped
+
+// ❌ NEVER use lwc:dom="manual" to insert raw HTML from user input
+// ❌ NEVER use innerHTML with unescaped user data
+```
+
+### 5. No Hardcoded Secrets
+
+```apex
+// ❌ NEVER
+String apiKey = 'sk-12345abcdef'; // Hardcoded credential!
+String endpoint = 'https://api.external.com/v1'; // Hardcoded endpoint!
+
+// ✅ ALWAYS — Named Credentials
+HttpRequest req = new HttpRequest();
+req.setEndpoint('callout:External_API/v1/resource');
+// Auth header is automatically added by Named Credential
+```
+
+---
+
+## Security Review Checklist (Code Review)
+
+Run this checklist on every PR:
+
+1. ✅ **CRUD/FLS enforced** — `WITH USER_MODE` or `WITH SECURITY_ENFORCED` on all SOQL
+2. ✅ **Sharing enforced** — `with sharing` on all classes (exceptions documented)
+3. ✅ **No SOQL injection** — Bind variables, `String.escapeSingleQuotes()`
+4. ✅ **No XSS** — No raw HTML insertion, template auto-escaping used
+5. ✅ **No hardcoded credentials** — Named Credentials for all external auth
+6. ✅ **No hardcoded IDs** — Custom Labels or Custom Metadata Types
+7. ✅ **stripInaccessible** — Used before DML with external/untrusted data
+8. ✅ **Error messages** — Don't expose internal stack traces to users
+9. ✅ **Test coverage** — Permission-based tests with `System.runAs()`
+
+---
+
+## AppExchange Security Review Readiness
+
+### Mandatory Scans
+
+| Tool | What It Checks | Required? |
+|------|---------------|-----------|
+| **Salesforce Code Analyzer** | PMD rules, Apex best practices | ✅ Recommended |
+| **Checkmarx** | SAST — Apex, VF, Lightning | ✅ Required for AppExchange |
+| **OWASP ZAP / Burp Suite** | DAST — Runtime vulnerabilities | ✅ Required (Chimera retired June 2025) |
+
+### Top Failure Reasons
+
+1. **Missing CRUD/FLS** — Most common failure. Fix: `WITH USER_MODE` everywhere.
+2. **SOQL Injection** — Dynamic queries without bind variables.
+3. **XSS** — Unescaped output in Visualforce/Aura.
+4. **Broken Access Control** — Missing `with sharing`, overly permissive profiles.
+5. **Insecure Authentication** — Hardcoded credentials, no Named Credentials.
+
+### 2026 Compliance Requirements
+
+| Requirement | Deadline | Impact |
+|------------|----------|--------|
+| MFA enforcement | Mid-2026 | All users must have MFA enabled |
+| Phishing-resistant MFA | Mid-2026 | Admin roles require hardware keys or passkeys |
+| Login IP restrictions | Ongoing | Stricter enforcement on elevated profiles |
+
+---
+
+## Security Testing Template
+
+```apex
+@IsTest
+private class SecurityTest {
+
+    @IsTest
+    static void testCrudFls_RestrictedUser() {
+        // Create user with minimum permissions
+        User restrictedUser = TestDataFactory.createStandardUser();
+        insert restrictedUser;
+
+        System.runAs(restrictedUser) {
+            Test.startTest();
+
+            // Verify FLS is enforced — user shouldn't see sensitive fields
+            try {
+                List<Account> accounts = AccountSelector.getByIds(
+                    new Set<Id>{ /* test account IDs */ }
+                );
+                // Verify restricted fields are not accessible
+            } catch (System.QueryException e) {
+                // Expected: WITH USER_MODE blocks inaccessible fields
+                System.assert(e.getMessage().contains('insufficient access'),
+                    'Should enforce FLS for restricted user');
+            }
+
+            Test.stopTest();
+        }
+    }
+}
+```