sf-forcekit 1.0.0

package/templates/ai-dir/inventory.md

@@ -0,0 +1,209 @@
+# Project Inventory
+
+> 🤖 **AUTO-UPDATED BY AI AGENTS** — Registry of everything that actually exists in this project.
+> Agents MUST consult this file before referencing any class, object, or component.
+> Agents MUST update this file after creating or deleting anything.
+
+---
+
+## How to Populate This File
+
+Run these commands and paste the output into the appropriate section below.
+Agents should do this at the **start of the first session** on a new project.
+
+```bash
+# List Apex classes in project
+ls force-app/main/default/classes/*.cls 2>/dev/null | xargs -I{} basename {} .cls | sort
+
+# List triggers in project
+ls force-app/main/default/triggers/*.trigger 2>/dev/null | xargs -I{} basename {} .trigger | sort
+
+# List LWC components
+ls -d force-app/main/default/lwc/*/ 2>/dev/null | xargs -I{} basename {} | sort
+
+# List custom objects
+ls force-app/main/default/objects/ 2>/dev/null | sort
+
+# List permission sets
+ls force-app/main/default/permissionsets/*.permissionset-meta.xml 2>/dev/null | xargs -I{} basename {} .permissionset-meta.xml | sort
+
+# List flows
+ls force-app/main/default/flows/*.flow-meta.xml 2>/dev/null | xargs -I{} basename {} .flow-meta.xml | sort
+```
+
+---
+
+## Custom Objects
+
+<!-- Agent: List every custom object in the project. Format:
+     | API Name | Label | Key Fields | Notes | -->
+
+| API Name | Label | Key Fields | Notes |
+|----------|-------|------------|-------|
+| _Populate from project_ | | | |
+
+---
+
+## Apex Classes
+
+<!-- Agent: List every Apex class. Categorize by layer. Format:
+     | Class Name | Layer | Object | Description | -->
+
+### Triggers
+
+| Trigger Name | Object | Handler Class |
+|-------------|--------|---------------|
+| CaseTrigger | Case | |
+
+### Handlers
+
+| Handler Name | Trigger | Service Class |
+|-------------|---------|---------------|
+| CaseService | | |
+| CaseTriggerHandler | | |
+
+### Services
+
+| Service Name | Object | Key Methods |
+|-------------|--------|-------------|
+| | | |
+
+### Selectors
+
+| Selector Name | Object | Key Queries |
+|--------------|--------|-------------|
+| CaseSelector | | |
+
+### Controllers (LWC / Aura)
+
+| Controller Name | Component | Key Methods |
+|----------------|-----------|-------------|
+| CaseController | | |
+| ChangePasswordController | | |
+| CommunitiesLandingController | | |
+| CommunitiesLoginController | | |
+| CommunitiesSelfRegConfirmController | | |
+| CommunitiesSelfRegController | | |
+| ForgotPasswordController | | |
+| LightningForgotPasswordController | | |
+| LightningLoginFormController | | |
+| LightningSelfRegisterController | | |
+| MicrobatchSelfRegController | | |
+| MyProfilePageController | | |
+| SiteLoginController | | |
+| SiteRegisterController | | |
+
+### Batch / Queueable / Schedulable
+
+| Class Name | Type | Purpose | Schedule |
+|-----------|------|---------|----------|
+| | | | |
+
+### Utilities / Helpers
+
+| Class Name | Purpose |
+|-----------|---------|
+| CaseServiceException | |
+
+### Test Classes
+
+| Test Class | Tests For | Coverage |
+|-----------|-----------|----------|
+| CaseControllerTest | | |
+| CaseSelectorTest | | |
+| CaseServiceTest | | |
+| CaseTriggerHandlerTest | | |
+| ChangePasswordControllerTest | | |
+| CommunitiesLandingControllerTest | | |
+| CommunitiesLoginControllerTest | | |
+| CommunitiesSelfRegConfirmControllerTest | | |
+| CommunitiesSelfRegControllerTest | | |
+| ForgotPasswordControllerTest | | |
+| LightningForgotPasswordControllerTest | | |
+| LightningLoginFormControllerTest | | |
+| LightningSelfRegisterControllerTest | | |
+| MicrobatchSelfRegControllerTest | | |
+| MyProfilePageControllerTest | | |
+| SiteLoginControllerTest | | |
+| SiteRegisterControllerTest | | |
+
+---
+
+## LWC Components
+
+<!-- Agent: List every LWC in the project. Format:
+     | Component Name | Targets | Data Source | Description | -->
+
+| Component Name | Targets | Data Source | Description |
+|---------------|---------|-------------|-------------|
+| | | Wire / Imperative / LDS | |
+
+---
+
+## Flows
+
+<!-- Agent: List every Flow. Format:
+     | Flow Name | Type | Object | Status | Purpose | -->
+
+| Flow Name | Type | Object | Status | Purpose |
+|-----------|------|--------|--------|---------|
+| | Before-Save / After-Save / Screen / Scheduled | | Active / Draft | |
+
+---
+
+## Custom Labels
+
+<!-- Agent: List Custom Labels used in the project. Format:
+     | Label Name | Value | Used In | -->
+
+| Label Name | Value | Used In |
+|-----------|-------|---------|
+| | | |
+
+---
+
+## Custom Metadata Types
+
+<!-- Agent: List CMDTs and their records. Format:
+     | CMDT Name | Key Records | Purpose | -->
+
+| CMDT Name | Key Records | Purpose |
+|----------|-------------|---------|
+| | | |
+
+---
+
+## Named Credentials
+
+<!-- Agent: List Named Credentials. Format:
+     | Name | Endpoint | Auth Type | Used By | -->
+
+| Name | Endpoint | Auth Type | Used By |
+|------|----------|-----------|---------|
+| | | | |
+
+---
+
+## Permission Sets
+
+| Permission Set Name | Purpose | Assigned To |
+|--------------------|---------|-------------|
+| Dashboard_Fields_Access | | |
+
+---
+
+## Platform Events
+
+| Event Name | Purpose | Publishers | Subscribers |
+|-----------|---------|-----------|-------------|
+| | | | |
+
+---
+
+## Last Full Scan
+
+<!-- Agent: Update this after running the populate commands above -->
+**Date:** 2026-05-22
+**Agent:** Auto-Scan Script
+**Method:** python3 .ai/scripts/update_state.py scan
+

package/templates/ai-dir/known-issues.md

@@ -0,0 +1,124 @@
+# Known Issues
+
+> Platform bugs, workarounds, project-specific tech debt, and gotchas.
+
+---
+
+## Platform Known Issues (API v66.0 — Spring '26)
+
+### Breaking Changes
+
+| Issue | Impact | Workaround | Reference |
+|-------|--------|------------|-----------|
+| Session IDs no longer supported in outbound messages | Outbound message integrations break if relying on Session ID | Migrate to OAuth-based auth with Named Credentials | [Spring '26 Release Notes] |
+| Flow: Enforces no-argument constructor visibility for invocable action parameters | Flow invocable actions with parameterized constructors may fail | Add no-arg constructor to all DTO/wrapper classes used in invocable actions | [Spring '26 Release Notes] |
+| Record-Triggered Flows respect internal writeable status of non-insertable fields | Before-save flows may behave differently with formula/rollup fields | Review flows that reference non-editable fields | [Spring '26 Release Notes] |
+
+### New Features to Leverage
+
+| Feature | Version | Impact |
+|---------|---------|--------|
+| **Apex Cursors** (GA) | v66.0 | Work with large SOQL result sets in chunks without hitting heap limits |
+| **GraphQL Mutations** | v66.0 | Replace simple `@AuraEnabled` CRUD Apex in LWC with declarative GraphQL |
+| **TypeScript for LWC** | v66.0 | `@salesforce/lightning-types` for full autocomplete and type safety |
+
+---
+
+## API Version Maintenance
+
+| Status | Versions | Notes |
+|--------|----------|-------|
+| ✅ Active | v55.0 — v66.0 | Fully supported |
+| ⚠️ Deprecated | v31.0 — v54.0 | Still works, will retire |
+| ❌ Retired | v21.0 — v30.0 | Returns `410: GONE` |
+
+**Rule:** Always use the latest GA version (v66.0) for new code. Check [Salesforce Trust](https://status.salesforce.com/) for maintenance windows.
+
+---
+
+## Common Gotchas
+
+### 1. Mixed DML
+
+Cannot perform DML on setup objects (User, PermissionSet) and non-setup objects (Account, Contact) in the same transaction.
+
+```apex
+// ❌ This fails
+insert new User(...);
+insert new Account(...);
+
+// ✅ Fix: Use @future or Queueable for setup DML
+@future
+public static void createUser(String email) { ... }
+```
+
+### 2. Trigger Recursion
+
+Triggers can re-fire when a service method updates related records. Use a static recursion guard.
+
+```apex
+public class TriggerRecursionGuard {
+    private static Set<Id> processedIds = new Set<Id>();
+
+    public static Boolean hasBeenProcessed(Id recordId) {
+        return processedIds.contains(recordId);
+    }
+
+    public static void markProcessed(Id recordId) {
+        processedIds.add(recordId);
+    }
+}
+```
+
+### 3. UNABLE_TO_LOCK_ROW
+
+Concurrent transactions on the same record cause row lock errors. Mitigate with:
+- Process parent records before children
+- Reduce transaction size
+- Add retry logic in Queueable
+- Avoid `FOR UPDATE` unless truly needed
+
+### 4. SOQL 101 in Tests
+
+Test methods share governor limits. Large test data + multiple service calls = SOQL limit hit.
+- Use `@TestSetup` to front-load data creation
+- Use `Test.startTest()` / `Test.stopTest()` to reset limits
+
+### 5. Deployment Order Dependencies
+
+| Deploy First | Then Deploy |
+|-------------|-------------|
+| Custom Objects / Fields | Apex Classes referencing them |
+| Apex Classes | Triggers referencing handler classes |
+| Permission Sets | Profiles referencing permission sets |
+| Custom Labels | Apex / Flows referencing labels |
+
+---
+
+## Project-Specific Issues
+
+<!-- Add issues specific to this project as they're discovered -->
+
+| Issue | Severity | Status | Workaround | Owner |
+|-------|----------|--------|------------|-------|
+| <!-- Example: Account trigger recursion with Contact updates --> | 🟡 Medium | Open | Static recursion guard | |
+| <!-- Add rows --> | | | | |
+
+---
+
+## Tech Debt Tracker
+
+| Item | Priority | Effort | Description |
+|------|----------|--------|-------------|
+| <!-- Example: Migrate Process Builders to Flows --> | P1 | Medium | 3 active PBs on Account, Contact, Opportunity |
+| <!-- Add rows --> | | | |
+
+---
+
+## Useful Links
+
+- [Salesforce Known Issues Portal](https://trailblazer.salesforce.com/issues_index)
+- [Salesforce Trust / Status](https://status.salesforce.com/)
+- [Release Notes (Latest)](https://help.salesforce.com/s/articleView?id=release-notes.salesforce_release_notes.htm)
+- [Apex Developer Guide](https://developer.salesforce.com/docs/atlas.en-us.apexcode.meta/apexcode/)
+- [LWC Developer Guide](https://developer.salesforce.com/docs/platform/lwc/guide)

package/templates/ai-dir/org-context.md

@@ -0,0 +1,110 @@
+# Org Context
+
+> Static reference for the target Salesforce org. Update when org changes or packages are installed.
+
+---
+
+## Org Details
+
+| Property | Value |
+|----------|-------|
+| **Org Alias** | `<insert_org_alias>` |
+| **Username** | `<insert_username>` |
+| **Edition** | `<insert_edition>` |
+| **API Version** | v66.0 |
+| **Instance** | `<insert_instance>` |
+| **Org ID** | `<insert_org_id>` |
+| **My Domain** | `<insert_my_domain>` |
+
+---
+
+## CLI Configuration
+
+| Property | Value |
+|----------|-------|
+| **CLI** | `@salesforce/cli` v2.x |
+| **Command prefix** | `sf` (NOT `sfdx`) |
+| **Default target org** | `--target-org <insert_org_alias>` |
+| **JSON output** | Add `--json` when parsing programmatically |
+
+### Common Commands
+
+```bash
+# Deploy
+sf project deploy start --target-org <insert_org_alias> --source-dir force-app
+
+# Retrieve
+sf project retrieve start --target-org <insert_org_alias> --metadata "ApexClass:AccountService"
+
+# SOQL Query
+sf data query --query "SELECT Id, Name FROM Account LIMIT 10" --target-org <insert_org_alias>
+
+# Tooling API Query
+sf data query --query "SELECT Id, Name FROM ApexClass" --target-org <insert_org_alias> --use-tooling-api
+
+# Run Tests
+sf apex run test --target-org <insert_org_alias> --code-coverage --result-format human
+
+# Open Org
+sf org open --target-org <insert_org_alias>
+
+# View Limits
+sf limits api display --target-org <insert_org_alias>
+```
+
+---
+
+## Governor Limits (<insert_edition>)
+
+| Limit | Value | Notes |
+|-------|-------|-------|
+| Daily API Requests | 15,000 | Monitor — adjust for your edition |
+| Data Storage | 5 MB | Update with actual storage limit |
+| File Storage | 20 MB | |
+| SOQL Queries / Txn | 100 | |
+| SOQL Rows / Txn | 50,000 | |
+| DML Statements / Txn | 150 | |
+| DML Rows / Txn | 10,000 | |
+| CPU Time (Sync) | 10,000 ms | |
+| CPU Time (Async) | 60,000 ms | |
+| Heap (Sync) | 6 MB | |
+| Heap (Async) | 12 MB | |
+| Callouts / Txn | 100 | |
+| Callout Timeout (each) | 10 sec | |
+| Callout Timeout (total) | 120 sec | |
+| Future Calls / Txn | 50 | Prefer Queueable |
+| Queueable Jobs / Txn | 50 | |
+
+---
+
+## Installed Packages
+
+| Package Name | Namespace | Version | Purpose |
+|-------------|-----------|---------|---------|
+| <!-- Add rows --> | | | |
+
+---
+
+## Enabled Features
+
+<!-- Check features enabled in this org -->
+
+- [ ] Einstein AI (Copilot / Agentforce)
+- [ ] Platform Events
+- [ ] Change Data Capture
+- [ ] Shield (Event Monitoring / Platform Encryption)
+- [ ] Experience Cloud (Communities)
+- [ ] Omni-Channel
+- [ ] Knowledge
+- [ ] Field Service
+- [ ] CPQ
+- [ ] Other: ___
+
+---
+
+## Connected Orgs / Sandboxes
+
+| Org/Sandbox | Type | Username | Purpose |
+|------------|------|----------|---------|
+| <insert_org_alias> (Dev) | <insert_edition> | <insert_username> | Primary dev |
+| <!-- Add rows --> | Full / Partial / Dev Pro | | |