@salesforce/afv-skills 1.8.0 → 1.9.0

package/skills/generating-mermaid-diagrams/references/usage-examples.md

@@ -0,0 +1,340 @@
+<!-- Parent: generating-mermaid-diagrams/SKILL.md -->
+# sf-diagram Usage Examples
+
+Real-world examples of using the sf-diagram skill.
+
+---
+
+## Example 1: OAuth Flow Diagram
+
+### Request
+```
+"Create a JWT Bearer OAuth flow diagram for our CI/CD pipeline integration"
+```
+
+### Generated Output
+
+#### Mermaid Diagram
+```mermaid
+%%{init: {'theme': 'base', 'themeVariables': {
+  'actorBkg': '#ddd6fe',
+  'actorTextColor': '#1f2937',
+  'actorBorder': '#6d28d9',
+  'signalColor': '#334155',
+  'signalTextColor': '#1f2937',
+  'noteBkgColor': '#f8fafc',
+  'noteTextColor': '#1f2937',
+  'noteBorderColor': '#334155'
+}}}%%
+sequenceDiagram
+    autonumber
+
+    box rgba(221,214,254,0.3) CI/CD PIPELINE
+        participant GH as 🔧 GitHub Actions
+        participant K as 🔐 Secrets Manager
+    end
+
+    box rgba(167,243,208,0.3) SALESFORCE
+        participant SF as ☁️ Salesforce
+    end
+
+    Note over GH,SF: JWT Bearer Flow for CI/CD
+
+    GH->>K: 1. Retrieve private key
+    K->>GH: 2. Return encrypted key
+
+    GH->>GH: 3. Create JWT
+    Note over GH: iss: consumer_key<br/>sub: deploy@company.com<br/>aud: login.salesforce.com
+
+    GH->>GH: 4. Sign with private key
+
+    GH->>SF: 5. POST /token (JWT assertion)
+
+    SF->>SF: 6. Verify signature
+    SF->>SF: 7. Validate claims
+
+    SF->>GH: 8. Access token
+
+    GH->>SF: 9. sf project deploy start
+    SF->>GH: 10. Deployment result
+```
+
+#### ASCII Fallback
+```
+┌───────────────────────┐     ┌────────────────────┐
+│   GitHub Actions      │     │     Salesforce     │
+│   (Private Key)       │     │   (Certificate)    │
+└───────────┬───────────┘     └─────────┬──────────┘
+            │                           │
+            │  1. Create JWT            │
+            │  2. Sign with key         │
+            │                           │
+            │  3. POST /token           │
+            │──────────────────────────>│
+            │                           │
+            │  4. Verify signature      │
+            │  5. Return access_token   │
+            │<──────────────────────────│
+            │                           │
+            │  6. sf project deploy start       │
+            │──────────────────────────>│
+```
+
+### Score
+```
+Score: 72/80 ⭐⭐⭐⭐⭐ Excellent
+├─ Accuracy: 20/20     ✓ All JWT Bearer steps correct
+├─ Clarity: 18/20      ✓ Clear labels, good flow
+├─ Completeness: 14/15 ✓ Includes CI/CD context
+├─ Styling: 12/15      ✓ Proper theming
+└─ Best Practices: 8/10 ✓ Good annotations
+```
+
+---
+
+## Example 2: Data Model ERD
+
+### Request
+```
+"Create an ERD for our custom Invoice system with Invoice__c, Invoice_Line_Item__c, and relationships to Account and Product"
+```
+
+### Generated Output
+
+#### Mermaid Diagram
+```mermaid
+%%{init: {'theme': 'base', 'themeVariables': {
+  'primaryColor': '#a5f3fc',
+  'primaryTextColor': '#1f2937',
+  'primaryBorderColor': '#0e7490',
+  'lineColor': '#334155',
+  'tertiaryColor': '#f8fafc'
+}}}%%
+erDiagram
+    Account ||--o{ Invoice__c : "billed to"
+    Account ||--o{ Contact : "has"
+    Invoice__c ||--|{ Invoice_Line_Item__c : "contains"
+    Product2 ||--o{ Invoice_Line_Item__c : "included in"
+
+    Account {
+        Id Id PK
+        Text Name "Required"
+        Text BillingStreet
+        Text BillingCity
+        Text BillingState
+        Text BillingPostalCode
+    }
+
+    Contact {
+        Id Id PK
+        Lookup AccountId FK "Account"
+        Text FirstName
+        Text LastName "Required"
+        Email Email
+    }
+
+    Invoice__c {
+        Id Id PK
+        AutoNumber Name "INV-00001"
+        MasterDetail Account__c FK "Account"
+        Lookup Billing_Contact__c FK "Contact"
+        Date Invoice_Date__c "Required"
+        Date Due_Date__c "Required"
+        Picklist Status__c "Draft, Sent, Paid, Overdue"
+        Currency Total_Amount__c "Roll-Up SUM"
+        Currency Paid_Amount__c
+        Formula Amount_Due__c "Total - Paid"
+        Text External_Id__c UK "Integration Key"
+    }
+
+    Invoice_Line_Item__c {
+        Id Id PK
+        AutoNumber Name "LI-00001"
+        MasterDetail Invoice__c FK "Invoice__c"
+        Lookup Product__c FK "Product2"
+        Number Quantity__c "Required"
+        Currency Unit_Price__c "Required"
+        Formula Line_Total__c "Qty × Price"
+        TextArea Description__c
+    }
+
+    Product2 {
+        Id Id PK
+        Text Name "Required"
+        Text ProductCode
+        Currency UnitPrice
+        Checkbox IsActive
+    }
+```
+
+#### ASCII Fallback
+```
+┌─────────────────────────┐       ┌─────────────────────────┐
+│        ACCOUNT          │       │        CONTACT          │
+├─────────────────────────┤       ├─────────────────────────┤
+│ Id (PK)                 │       │ Id (PK)                 │
+│ Name (Required)         │──┐    │ AccountId (FK) ─────────│───┐
+│ BillingStreet           │  │    │ FirstName               │   │
+│ BillingCity             │  │    │ LastName (Required)     │   │
+│ BillingState            │  │    │ Email                   │   │
+│ BillingPostalCode       │  │    └─────────────────────────┘   │
+└─────────────────────────┘  │                                  │
+              │               │                                  │
+              │ 1:N           └──────────────────────────────────┘
+              ▼
+┌─────────────────────────┐
+│      INVOICE__C         │
+├─────────────────────────┤
+│ Id (PK)                 │
+│ Name (Auto: INV-00001)  │
+│ Account__c (MD)         │
+│ Billing_Contact__c (LK) │
+│ Invoice_Date__c (Req)   │
+│ Due_Date__c (Req)       │
+│ Status__c (Picklist)    │
+│ Total_Amount__c (Roll)  │
+│ Amount_Due__c (Formula) │
+│ External_Id__c (UK)     │
+└─────────────┬───────────┘
+              │
+              │ 1:N (Master-Detail)
+              ▼
+┌─────────────────────────┐       ┌─────────────────────────┐
+│  INVOICE_LINE_ITEM__C   │       │       PRODUCT2          │
+├─────────────────────────┤       ├─────────────────────────┤
+│ Id (PK)                 │       │ Id (PK)                 │
+│ Name (Auto: LI-00001)   │       │ Name (Required)         │
+│ Invoice__c (MD) ────────│──┘    │ ProductCode             │
+│ Product__c (LK) ────────│──────>│ UnitPrice               │
+│ Quantity__c (Req)       │       │ IsActive                │
+│ Unit_Price__c (Req)     │       └─────────────────────────┘
+│ Line_Total__c (Formula) │
+│ Description__c          │
+└─────────────────────────┘
+```
+
+### Score
+```
+Score: 74/80 ⭐⭐⭐⭐⭐ Excellent
+├─ Accuracy: 20/20     ✓ All relationships correct
+├─ Clarity: 19/20      ✓ Clear field annotations
+├─ Completeness: 15/15 ✓ All objects included
+├─ Styling: 13/15      ✓ Good layout
+└─ Best Practices: 7/10  ⚠ Could add more field comments
+```
+
+---
+
+## Example 3: Integration Sequence
+
+### Request
+```
+"Diagram our real-time Order sync from Salesforce to SAP using Platform Events"
+```
+
+### Generated Output
+
+#### Mermaid Diagram
+```mermaid
+%%{init: {'theme': 'base', 'themeVariables': {
+  'actorBkg': '#ddd6fe',
+  'actorTextColor': '#1f2937',
+  'actorBorder': '#6d28d9',
+  'signalColor': '#334155',
+  'signalTextColor': '#1f2937',
+  'noteBkgColor': '#f8fafc',
+  'noteTextColor': '#1f2937',
+  'noteBorderColor': '#334155'
+}}}%%
+sequenceDiagram
+    autonumber
+
+    box rgba(167,243,208,0.3) SALESFORCE
+        participant T as 🔄 Order Trigger
+        participant PE as 📢 Order_Sync__e
+    end
+
+    box rgba(254,215,170,0.3) INTEGRATION
+        participant MW as 🔄 MuleSoft
+    end
+
+    box rgba(165,243,252,0.3) SAP
+        participant SAP as 🏭 SAP S/4HANA
+    end
+
+    Note over T,SAP: Real-time Order Sync (Platform Events)
+
+    T->>T: 1. Order record saved
+    Note over T: Status changed to 'Approved'
+
+    T->>PE: 2. Publish Platform Event
+    Note over T,PE: EventBus.publish(<br/>  new Order_Sync__e(<br/>    Order_Id__c,<br/>    Action__c='CREATE'<br/>  )<br/>)
+
+    PE-)MW: 3. Event delivered (CometD)
+    Note over PE,MW: /event/Order_Sync__e
+
+    activate MW
+
+    MW->>MW: 4. Transform to SAP format
+    Note over MW: Map SF Order → SAP Sales Order
+
+    MW->>SAP: 5. POST /sap/api/salesorders
+    Note over MW,SAP: IDOC or REST API
+
+    alt Success
+        SAP->>MW: 6a. 201 Created
+        Note over SAP,MW: SAP Order #: 4500012345
+
+        MW->>PE: 7a. Publish confirmation
+        Note over MW,PE: Order_Sync_Status__e<br/>Status='SUCCESS'
+
+    else Validation Error
+        SAP->>MW: 6b. 400 Bad Request
+        Note over SAP,MW: Missing required field
+
+        MW->>PE: 7b. Publish error
+        Note over MW,PE: Order_Sync_Status__e<br/>Status='ERROR'
+    end
+
+    deactivate MW
+
+    Note over T: Flow updates Order<br/>with SAP reference
+```
+
+### Score
+```
+Score: 70/80 ⭐⭐⭐⭐ Very Good
+├─ Accuracy: 19/20     ✓ Platform Event pattern correct
+├─ Clarity: 18/20      ✓ Good error handling shown
+├─ Completeness: 13/15 ✓ Main paths covered
+├─ Styling: 12/15      ✓ Good use of boxes
+└─ Best Practices: 8/10 ✓ Shows async pattern
+```
+
+---
+
+## Example 4: Combined Request
+
+### Request
+```
+"I need to document our partner portal authentication.
+Create: 1) The OAuth flow for partner login, 2) The data model showing Partner Account, Portal User, and Opportunities they can see"
+```
+
+### Generated Output
+
+The skill generates two diagrams:
+
+1. **OAuth Authorization Code + PKCE Flow** (for the portal)
+2. **ERD showing Partner Access Model**
+
+Both with Mermaid and ASCII versions.
+
+---
+
+## Tips for Best Results
+
+1. **Be specific** - "JWT Bearer for CI/CD" is better than just "OAuth"
+2. **Name your systems** - "Salesforce to SAP" produces clearer diagrams
+3. **Mention custom objects** - Include `__c` suffix so we know they're custom
+4. **Request both formats** - If you need ASCII fallback, mention it explicitly

package/skills/generating-mermaid-diagrams/scripts/README.md

@@ -0,0 +1,160 @@
+# Mermaid Preview Server
+
+A lightweight HTTP server with live reload for previewing Mermaid diagrams in your browser.
+
+## Features
+
+- **Live Reload**: Browser automatically refreshes when your diagram file changes
+- **Zero Dependencies**: Pure Python stdlib - no pip install required
+- **Background Mode**: Server runs in background, doesn't block your terminal
+- **Dark Mode**: Automatically matches your system theme preference
+- **Copy & Download**: Copy Mermaid code or download as SVG directly from browser
+
+## Quick Start
+
+```bash
+# Start the server (opens browser automatically)
+python mermaid_preview.py start --file /tmp/my-diagram.mmd
+
+# Check if server is running
+python mermaid_preview.py status
+
+# Stop the server
+python mermaid_preview.py stop
+```
+
+## Usage
+
+### Starting the Server
+
+```bash
+python mermaid_preview.py start --file <path-to-mermaid-file>
+```
+
+**Options:**
+| Option | Description | Default |
+|--------|-------------|---------|
+| `--file`, `-f` | Mermaid file to watch | `/tmp/mermaid-preview.mmd` |
+| `--port`, `-p` | Server port | `8765` |
+| `--no-browser` | Don't auto-open browser | `false` |
+| `--pid-file` | PID file location | `/tmp/mermaid-preview.pid` |
+
+### Stopping the Server
+
+```bash
+python mermaid_preview.py stop
+```
+
+### Checking Status
+
+```bash
+python mermaid_preview.py status
+```
+
+## How It Works
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    Browser Tab                               │
+│  ┌─────────────────────────────────────────────────────┐    │
+│  │           Mermaid Diagram (rendered)                 │    │
+│  └─────────────────────────────────────────────────────┘    │
+│                         ↑                                    │
+│            SSE: http://localhost:8765/events                 │
+│              (receives "reload" events)                      │
+└─────────────────────────────────────────────────────────────┘
+                          ↑
+┌─────────────────────────────────────────────────────────────┐
+│              mermaid_preview.py (background)                 │
+│                                                              │
+│  ┌───────────────────────────────────────────────────────┐  │
+│  │             HTTP Server :8765                          │  │
+│  │  GET /           → Serves rendered HTML                │  │
+│  │  GET /events     → SSE stream for live reload          │  │
+│  └───────────────────────────────────────────────────────┘  │
+│                             ↑                                │
+│  ┌───────────────────────────────────────────────────────┐  │
+│  │  File Watcher (polls every 500ms)                      │  │
+│  │  Triggers reload when file mtime changes               │  │
+│  └───────────────────────────────────────────────────────┘  │
+└─────────────────────────────────────────────────────────────┘
+                          ↑
+                 /tmp/mermaid-preview.mmd
+                     (your diagram file)
+```
+
+1. **HTTP Server** serves the HTML page with your Mermaid diagram
+2. **File Watcher** monitors your diagram file for changes (polling mtime every 500ms)
+3. **SSE (Server-Sent Events)** pushes "reload" events to the browser when file changes
+4. **Browser** automatically refreshes to show the updated diagram
+
+## Integration with sf-diagram Skill
+
+When using the sf-diagram skill, you can request a preview:
+
+1. Ask sf-diagram to create a diagram
+2. Say "preview this diagram" or "show me the preview"
+3. The skill will:
+   - Save the diagram to `/tmp/mermaid-preview.mmd`
+   - Start the preview server
+   - Give you the URL: `http://localhost:8765`
+4. As you iterate on the diagram, the browser auto-refreshes
+5. When done, say "stop preview" or run `python mermaid_preview.py stop`
+
+## Browser Features
+
+### Copy Mermaid Code
+Click the "Copy Mermaid Code" button to copy the raw Mermaid syntax to your clipboard.
+
+### Download SVG
+Click "Download SVG" to save the rendered diagram as an SVG file.
+
+### Connection Status
+The status indicator shows whether you're connected to the live reload server:
+- **● Connected** (green): Live reload is active
+- **○ Disconnected** (red): Server connection lost, will auto-reconnect
+
+## Troubleshooting
+
+### Port Already in Use
+
+```bash
+# Check if something is using port 8765
+lsof -i :8765
+
+# Use a different port
+python mermaid_preview.py start --file diagram.mmd --port 8766
+```
+
+### Server Won't Start
+
+```bash
+# Remove stale PID file
+rm /tmp/mermaid-preview.pid
+
+# Try starting again
+python mermaid_preview.py start --file diagram.mmd
+```
+
+### Browser Doesn't Auto-Open
+
+The `--no-browser` flag prevents auto-opening. To manually open:
+1. Start server with `python mermaid_preview.py start --file diagram.mmd`
+2. Open `http://localhost:8765` in your browser
+
+### Live Reload Not Working
+
+1. Check the connection status in the browser (should be "Connected")
+2. Verify the file path is correct (shown in the browser)
+3. Make sure you're saving the file (not just editing)
+4. Try refreshing the browser manually
+
+## Requirements
+
+- Python 3.7+
+- macOS or Linux (uses `os.fork()` for background mode)
+- Modern browser with SSE support (all major browsers)
+
+## License
+
+MIT License