@salesforce/afv-skills 1.8.0 → 1.9.0

package/skills/building-sf-integrations/hooks/scripts/suggest_credential_setup.py

@@ -0,0 +1,271 @@
+#!/usr/bin/env python3
+"""
+Credential Setup Suggestion Hook for building-sf-integrations
+
+Detects when credential metadata files are created and suggests
+running the appropriate automation scripts.
+
+File patterns detected:
+- *.namedCredential-meta.xml → configure-named-credential.sh
+- *.externalCredential-meta.xml → configure-named-credential.sh
+- *cspTrustedSite-meta.xml → Endpoint security configured
+- *remoteSite-meta.xml → Endpoint security configured
+
+Called automatically via PostToolUse hook on Write operations.
+"""
+
+import json
+import os
+import re
+import sys
+from pathlib import Path
+
+# File pattern matchers
+PATTERNS = {
+    'named_credential': re.compile(r'\.namedCredential-meta\.xml$', re.IGNORECASE),
+    'external_credential': re.compile(r'\.externalCredential-meta\.xml$', re.IGNORECASE),
+    'csp_trusted_site': re.compile(r'\.cspTrustedSite-meta\.xml$', re.IGNORECASE),
+    'remote_site': re.compile(r'\.remoteSiteSetting-meta\.xml$|\.remoteSite-meta\.xml$', re.IGNORECASE),
+    'external_service': re.compile(r'\.externalServiceRegistration-meta\.xml$', re.IGNORECASE),
+}
+
+# Script recommendations per file type
+SCRIPT_RECOMMENDATIONS = {
+    'named_credential': {
+        'script': 'configure-named-credential.sh',
+        'description': 'Set API key securely via ConnectApi (Enhanced Named Credentials)',
+        'usage': './scripts/configure-named-credential.sh <org-alias>',
+        'next_steps': [
+            'Deploy metadata: sf project deploy start --metadata NamedCredential:<name>',
+            'Run script to configure API key securely',
+            'Test connection in Setup → Named Credentials'
+        ]
+    },
+    'external_credential': {
+        'script': 'configure-named-credential.sh',
+        'description': 'Configure External Credential with ConnectApi',
+        'usage': './scripts/configure-named-credential.sh <org-alias>',
+        'next_steps': [
+            'Deploy External Credential first',
+            'Deploy associated Named Credential',
+            'Run script to set authentication parameters'
+        ]
+    },
+    'csp_trusted_site': {
+        'script': None,
+        'description': 'CSP Trusted Site created for endpoint security',
+        'usage': None,
+        'next_steps': [
+            'Deploy: sf project deploy start --metadata CspTrustedSite:<name>',
+            'Verify in Setup → CSP Trusted Sites'
+        ]
+    },
+    'remote_site': {
+        'script': None,
+        'description': 'Remote Site Setting created (legacy endpoint security)',
+        'usage': None,
+        'next_steps': [
+            'Deploy: sf project deploy start --metadata RemoteSiteSetting:<name>',
+            'Consider migrating to CSP Trusted Sites for modern approach'
+        ]
+    },
+    'external_service': {
+        'script': None,
+        'description': 'External Service registration created',
+        'usage': None,
+        'next_steps': [
+            'Ensure Named Credential is configured first',
+            'Deploy: sf project deploy start --metadata ExternalServiceRegistration:<name>',
+            'Apex classes will be auto-generated from OpenAPI spec'
+        ]
+    }
+}
+
+
+def detect_file_type(file_path: str) -> str | None:
+    """Detect the credential file type from the file path."""
+    filename = os.path.basename(file_path)
+
+    for file_type, pattern in PATTERNS.items():
+        if pattern.search(filename):
+            return file_type
+
+    return None
+
+
+def extract_credential_name(file_path: str, file_type: str) -> str:
+    """Extract the credential name from the file path."""
+    filename = os.path.basename(file_path)
+
+    # Remove the metadata suffix to get the credential name
+    patterns = {
+        'named_credential': r'(.+)\.namedCredential-meta\.xml$',
+        'external_credential': r'(.+)\.externalCredential-meta\.xml$',
+        'csp_trusted_site': r'(.+)\.cspTrustedSite-meta\.xml$',
+        'remote_site': r'(.+)\.(?:remoteSiteSetting|remoteSite)-meta\.xml$',
+        'external_service': r'(.+)\.externalServiceRegistration-meta\.xml$',
+    }
+
+    pattern = patterns.get(file_type)
+    if pattern:
+        match = re.match(pattern, filename, re.IGNORECASE)
+        if match:
+            return match.group(1)
+
+    return filename
+
+
+def analyze_file_content(file_path: str) -> dict:
+    """Analyze the file content for additional context."""
+    context = {
+        'auth_protocol': None,
+        'endpoint_url': None,
+        'has_oauth': False,
+        'has_certificate': False
+    }
+
+    try:
+        with open(file_path, 'r', encoding='utf-8') as f:
+            content = f.read()
+
+        # Detect authentication protocol
+        if '<authProtocol>OAuth</authProtocol>' in content:
+            context['auth_protocol'] = 'OAuth 2.0'
+            context['has_oauth'] = True
+        elif '<authProtocol>Jwt</authProtocol>' in content:
+            context['auth_protocol'] = 'JWT Bearer'
+        elif '<authProtocol>Custom</authProtocol>' in content:
+            context['auth_protocol'] = 'Custom (API Key)'
+        elif '<authProtocol>Certificate</authProtocol>' in content:
+            context['auth_protocol'] = 'Certificate'
+            context['has_certificate'] = True
+
+        # Extract endpoint URL
+        url_match = re.search(r'<endpoint>([^<]+)</endpoint>', content)
+        if url_match:
+            context['endpoint_url'] = url_match.group(1)
+
+        # Check for Named Credential URL pattern
+        url_match = re.search(r'<url>([^<]+)</url>', content)
+        if url_match:
+            context['endpoint_url'] = url_match.group(1)
+
+    except Exception:
+        pass  # File analysis is optional
+
+    return context
+
+
+def generate_suggestion_message(file_type: str, cred_name: str, file_context: dict) -> str:
+    """Generate the suggestion message for Claude."""
+    recommendation = SCRIPT_RECOMMENDATIONS.get(file_type, {})
+
+    lines = [
+        '',
+        '═' * 60,
+        '🔐 CREDENTIAL CONFIGURATION DETECTED',
+        '═' * 60,
+        '',
+        f'📄 File Type: {file_type.replace("_", " ").title()}',
+        f'📛 Name: {cred_name}',
+    ]
+
+    if file_context.get('auth_protocol'):
+        lines.append(f'🔑 Auth Protocol: {file_context["auth_protocol"]}')
+
+    if file_context.get('endpoint_url'):
+        lines.append(f'🌐 Endpoint: {file_context["endpoint_url"]}')
+
+    lines.append('')
+
+    if recommendation.get('script'):
+        lines.extend([
+            '┌─────────────────────────────────────────────────────────┐',
+            '│  🚀 AUTOMATION SCRIPT AVAILABLE                         │',
+            '├─────────────────────────────────────────────────────────┤',
+            f'│  Script: {recommendation["script"]:<46} │',
+            f'│  Purpose: {recommendation["description"][:44]:<44} │',
+            '├─────────────────────────────────────────────────────────┤',
+            '│  💡 OFFER TO RUN:                                       │',
+            f'│  {recommendation["usage"]:<55} │',
+            '└─────────────────────────────────────────────────────────┘',
+            '',
+        ])
+
+    lines.extend([
+        '📋 NEXT STEPS:',
+        '─' * 60,
+    ])
+
+    for i, step in enumerate(recommendation.get('next_steps', []), 1):
+        lines.append(f'   {i}. {step}')
+
+    # Add OAuth-specific suggestion
+    if file_context.get('has_oauth'):
+        lines.extend([
+            '',
+            '⚠️  OAuth detected: Consider using /configuring-connected-apps to',
+            '    create the Connected App for this credential.',
+        ])
+
+    lines.extend([
+        '',
+        '═' * 60,
+    ])
+
+    return '\n'.join(lines)
+
+
+def main():
+    """Main entry point for the hook."""
+    # Get file path from command line or stdin
+    file_path = None
+
+    if len(sys.argv) > 1:
+        file_path = sys.argv[1]
+    else:
+        # Try to read from stdin (hook input)
+        try:
+            hook_input = json.load(sys.stdin)
+            tool_input = hook_input.get('tool_input', {})
+            file_path = tool_input.get('file_path', '')
+        except (json.JSONDecodeError, IOError):
+            pass
+
+    if not file_path:
+        # No file path, exit silently
+        print(json.dumps({'continue': True}))
+        return 0
+
+    # Detect file type
+    file_type = detect_file_type(file_path)
+
+    if not file_type:
+        # Not a credential file, exit silently
+        print(json.dumps({'continue': True}))
+        return 0
+
+    # Extract credential name
+    cred_name = extract_credential_name(file_path, file_type)
+
+    # Analyze file content
+    file_context = analyze_file_content(file_path)
+
+    # Generate suggestion message
+    message = generate_suggestion_message(file_type, cred_name, file_context)
+
+    # Output hook result
+    result = {
+        'continue': True,
+        'hookSpecificOutput': {
+            'hookEventName': 'PostToolUse',
+            'additionalContext': message
+        }
+    }
+
+    print(json.dumps(result))
+    return 0
+
+
+if __name__ == '__main__':
+    sys.exit(main())

package/skills/building-sf-integrations/hooks/scripts/validate_integration.py

@@ -0,0 +1,363 @@
+#!/usr/bin/env python3
+"""
+building-sf-integrations Validation Script
+
+Validates integration-related files against best practices.
+Scoring: 120 points across 6 categories.
+
+Categories:
+- Security (30 points)
+- Error Handling (25 points)
+- Bulkification (20 points)
+- Architecture (20 points)
+- Best Practices (15 points)
+- Documentation (10 points)
+"""
+
+import sys
+import re
+import os
+from pathlib import Path
+
+# Scoring configuration
+MAX_SCORE = 120
+CATEGORIES = {
+    'security': {'max': 30, 'score': 0, 'issues': []},
+    'error_handling': {'max': 25, 'score': 0, 'issues': []},
+    'bulkification': {'max': 20, 'score': 0, 'issues': []},
+    'architecture': {'max': 20, 'score': 0, 'issues': []},
+    'best_practices': {'max': 15, 'score': 0, 'issues': []},
+    'documentation': {'max': 10, 'score': 0, 'issues': []}
+}
+
+# File type patterns
+APEX_PATTERN = re.compile(r'\.cls$|\.trigger$')
+XML_PATTERN = re.compile(r'\.xml$')
+NAMED_CRED_PATTERN = re.compile(r'namedCredential.*\.xml$', re.IGNORECASE)
+
+
+def validate_apex_file(content: str, filename: str) -> None:
+    """Validate Apex class/trigger for integration patterns."""
+
+    # Security checks (30 points)
+    security_score = 30
+
+    # Check for hardcoded credentials
+    if re.search(r'Authorization.*Bearer\s+[a-zA-Z0-9_\-]{20,}', content):
+        security_score -= 15
+        CATEGORIES['security']['issues'].append('❌ Hardcoded Bearer token detected')
+
+    if re.search(r'api[_-]?key\s*=\s*[\'"][a-zA-Z0-9]{10,}', content, re.IGNORECASE):
+        security_score -= 15
+        CATEGORIES['security']['issues'].append('❌ Hardcoded API key detected')
+
+    if re.search(r'password\s*=\s*[\'"][^\'"]{5,}', content, re.IGNORECASE):
+        security_score -= 15
+        CATEGORIES['security']['issues'].append('❌ Hardcoded password detected')
+
+    # Check for Named Credential usage
+    if 'HttpRequest' in content:
+        if 'callout:' in content:
+            if not CATEGORIES['security']['issues']:
+                CATEGORIES['security']['issues'].append('✅ Named Credential used')
+        else:
+            security_score -= 10
+            CATEGORIES['security']['issues'].append('⚠️ HttpRequest without Named Credential')
+
+    CATEGORIES['security']['score'] = max(0, security_score)
+
+    # Error Handling checks (25 points)
+    error_score = 25
+
+    if 'HttpRequest' in content or 'Http().send' in content:
+        # Check for try-catch
+        if 'try' not in content or 'catch' not in content:
+            error_score -= 10
+            CATEGORIES['error_handling']['issues'].append('❌ Missing try-catch for callout')
+        else:
+            CATEGORIES['error_handling']['issues'].append('✅ Try-catch present')
+
+        # Check for CalloutException handling
+        if 'CalloutException' in content:
+            CATEGORIES['error_handling']['issues'].append('✅ CalloutException handled')
+        else:
+            error_score -= 5
+            CATEGORIES['error_handling']['issues'].append('⚠️ CalloutException not explicitly caught')
+
+        # Check for status code handling
+        if 'getStatusCode()' in content:
+            CATEGORIES['error_handling']['issues'].append('✅ Status code checked')
+        else:
+            error_score -= 5
+            CATEGORIES['error_handling']['issues'].append('⚠️ Status code not checked')
+
+        # Check for timeout setting
+        if 'setTimeout' in content:
+            CATEGORIES['error_handling']['issues'].append('✅ Timeout configured')
+        else:
+            error_score -= 5
+            CATEGORIES['error_handling']['issues'].append('⚠️ No timeout set (default may be too short)')
+
+    CATEGORIES['error_handling']['score'] = max(0, error_score)
+
+    # Bulkification checks (20 points)
+    bulk_score = 20
+
+    # Check for SOQL in loops
+    if re.search(r'for\s*\([^)]+\)\s*\{[^}]*\[SELECT', content, re.DOTALL | re.IGNORECASE):
+        bulk_score -= 10
+        CATEGORIES['bulkification']['issues'].append('❌ SOQL in loop')
+
+    # Check for DML in loops
+    if re.search(r'for\s*\([^)]+\)\s*\{[^}]*(insert|update|delete)\s+', content, re.DOTALL | re.IGNORECASE):
+        bulk_score -= 10
+        CATEGORIES['bulkification']['issues'].append('❌ DML in loop')
+
+    # Check for HTTP callout in loops (expensive)
+    if re.search(r'for\s*\([^)]+\)\s*\{[^}]*\.send\(', content, re.DOTALL):
+        bulk_score -= 5
+        CATEGORIES['bulkification']['issues'].append('⚠️ HTTP callout in loop (consider batching)')
+
+    if bulk_score == 20:
+        CATEGORIES['bulkification']['issues'].append('✅ No obvious bulkification issues')
+
+    CATEGORIES['bulkification']['score'] = max(0, bulk_score)
+
+    # Architecture checks (20 points)
+    arch_score = 20
+
+    # Check if class implements proper interfaces for callouts
+    if 'implements Queueable' in content and 'Database.AllowsCallouts' in content:
+        CATEGORIES['architecture']['issues'].append('✅ Proper Queueable + AllowsCallouts pattern')
+    elif 'Queueable' in content and 'AllowsCallouts' not in content:
+        if 'HttpRequest' in content or 'Http(' in content:
+            arch_score -= 10
+            CATEGORIES['architecture']['issues'].append('❌ Queueable with callout missing AllowsCallouts')
+
+    # Check for trigger context callout (should be async)
+    if '.trigger' in filename.lower():
+        if 'Http(' in content or 'HttpRequest' in content:
+            arch_score -= 15
+            CATEGORIES['architecture']['issues'].append('❌ Synchronous callout in trigger (must use async)')
+
+    CATEGORIES['architecture']['score'] = max(0, arch_score)
+
+    # Best Practices checks (15 points)
+    bp_score = 15
+
+    # Check for logging
+    if 'System.debug' in content:
+        CATEGORIES['best_practices']['issues'].append('✅ Debug logging present')
+    else:
+        bp_score -= 5
+        CATEGORIES['best_practices']['issues'].append('⚠️ No debug logging')
+
+    # Check for proper HTTP methods
+    if re.search(r'setMethod\s*\(\s*[\'"](?:GET|POST|PUT|PATCH|DELETE)[\'"]\s*\)', content):
+        CATEGORIES['best_practices']['issues'].append('✅ Standard HTTP method used')
+
+    CATEGORIES['best_practices']['score'] = max(0, bp_score)
+
+    # Documentation checks (10 points)
+    doc_score = 10
+
+    # Check for ApexDoc
+    if '/**' in content and '@description' in content:
+        CATEGORIES['documentation']['issues'].append('✅ ApexDoc present')
+    else:
+        doc_score -= 5
+        CATEGORIES['documentation']['issues'].append('⚠️ Missing ApexDoc comments')
+
+    # Check for class-level documentation
+    if re.search(r'/\*\*[\s\S]*?\*/\s*public\s+(with sharing\s+)?class', content):
+        CATEGORIES['documentation']['issues'].append('✅ Class-level documentation')
+
+    CATEGORIES['documentation']['score'] = max(0, doc_score)
+
+
+def validate_named_credential(content: str) -> None:
+    """Validate Named Credential XML."""
+
+    # Security checks
+    security_score = 30
+
+    # Check for hardcoded password in XML (should never be there)
+    if '<password>' in content and re.search(r'<password>[^<]+</password>', content):
+        password_value = re.search(r'<password>([^<]+)</password>', content)
+        if password_value and len(password_value.group(1)) > 0:
+            security_score -= 15
+            CATEGORIES['security']['issues'].append('⚠️ Password value in metadata (should be empty, set via UI)')
+
+    # Check for protocol
+    if '<protocol>Oauth</protocol>' in content:
+        CATEGORIES['security']['issues'].append('✅ OAuth authentication configured')
+    elif '<protocol>Password</protocol>' in content:
+        CATEGORIES['security']['issues'].append('✅ Password authentication configured')
+        security_score -= 5  # OAuth preferred over password
+    elif '<protocol>NoAuthentication</protocol>' in content:
+        CATEGORIES['security']['issues'].append('⚠️ No authentication (verify this is intentional)')
+        security_score -= 10
+
+    CATEGORIES['security']['score'] = max(0, security_score)
+
+    # Best practices
+    bp_score = 15
+
+    if '<allowMergeFieldsInBody>true</allowMergeFieldsInBody>' in content:
+        CATEGORIES['best_practices']['issues'].append('✅ Merge fields in body enabled')
+
+    if '<allowMergeFieldsInHeader>true</allowMergeFieldsInHeader>' in content:
+        CATEGORIES['best_practices']['issues'].append('✅ Merge fields in header enabled')
+
+    CATEGORIES['best_practices']['score'] = bp_score
+
+    # Named Credential XML files are configuration-only — Error Handling,
+    # Bulkification, Architecture, and Documentation categories are not
+    # applicable. Grant full marks for non-applicable categories so that
+    # valid XML files are not penalized by the Apex-oriented rubric.
+    CATEGORIES['error_handling']['score'] = CATEGORIES['error_handling']['max']
+    CATEGORIES['bulkification']['score'] = CATEGORIES['bulkification']['max']
+    CATEGORIES['architecture']['score'] = CATEGORIES['architecture']['max']
+    CATEGORIES['documentation']['score'] = CATEGORIES['documentation']['max']
+
+
+def validate_platform_event(content: str) -> None:
+    """Validate Platform Event definition."""
+
+    # Check event type
+    if '<eventType>HighVolume</eventType>' in content:
+        CATEGORIES['best_practices']['issues'].append('✅ High Volume event type')
+        CATEGORIES['best_practices']['score'] = 15
+    elif '<eventType>StandardVolume</eventType>' in content:
+        CATEGORIES['best_practices']['issues'].append('✅ Standard Volume event type')
+        CATEGORIES['best_practices']['score'] = 15
+
+    # Check publish behavior
+    if '<publishBehavior>PublishAfterCommit</publishBehavior>' in content:
+        CATEGORIES['architecture']['issues'].append('✅ PublishAfterCommit (recommended)')
+        CATEGORIES['architecture']['score'] = 20
+    elif '<publishBehavior>PublishImmediately</publishBehavior>' in content:
+        CATEGORIES['architecture']['issues'].append('⚠️ PublishImmediately (verify this is intentional)')
+        CATEGORIES['architecture']['score'] = 15
+
+
+def calculate_total_score() -> int:
+    """Calculate total score from all categories."""
+    return sum(cat['score'] for cat in CATEGORIES.values())
+
+
+def get_rating(score: int) -> str:
+    """Get star rating based on score."""
+    percentage = (score / MAX_SCORE) * 100
+    if percentage >= 90:
+        return '⭐⭐⭐⭐⭐ Excellent'
+    elif percentage >= 80:
+        return '⭐⭐⭐⭐ Very Good'
+    elif percentage >= 70:
+        return '⭐⭐⭐ Good'
+    elif percentage >= 60:
+        return '⭐⭐ Needs Work'
+    else:
+        return '⭐ Critical'
+
+
+def print_score_report(filename: str) -> None:
+    """Print formatted score report."""
+    total = calculate_total_score()
+    rating = get_rating(total)
+
+    print(f'\n📊 INTEGRATION SCORE: {total}/{MAX_SCORE} {rating}')
+    print('═' * 50)
+
+    category_icons = {
+        'security': '🔐',
+        'error_handling': '⚠️',
+        'bulkification': '📦',
+        'architecture': '🏗️',
+        'best_practices': '✅',
+        'documentation': '📝'
+    }
+
+    for cat_name, cat_data in CATEGORIES.items():
+        icon = category_icons.get(cat_name, '•')
+        max_score = cat_data['max']
+        score = cat_data['score']
+        pct = (score / max_score * 100) if max_score > 0 else 0
+        bar = '█' * int(pct / 10) + '░' * (10 - int(pct / 10))
+
+        print(f'\n{icon} {cat_name.replace("_", " ").title():18} {score:2}/{max_score:2}  {bar} {pct:.0f}%')
+
+        for issue in cat_data['issues']:
+            print(f'   {issue}')
+
+    print('\n' + '═' * 50)
+
+    if total < 54:
+        print('🚫 DEPLOYMENT BLOCKED - Score below 45% threshold')
+    elif total < 72:
+        print('⚠️ WARNING - Review issues before deployment')
+    else:
+        print('✅ PASSED - Ready for deployment')
+
+
+def main():
+    import json
+
+    file_path = None
+
+    # Mode 1: Hook mode - read from stdin JSON (PostToolUse hooks)
+    if not sys.stdin.isatty():
+        try:
+            hook_input = json.load(sys.stdin)
+            tool_input = hook_input.get("tool_input", {})
+            file_path = tool_input.get("file_path", "")
+        except (json.JSONDecodeError, EOFError):
+            pass
+
+    # Mode 2: CLI mode - read from command-line argument
+    if not file_path and len(sys.argv) >= 2:
+        file_path = sys.argv[1]
+
+    # Skip if no file path
+    if not file_path:
+        print('Usage: validate_integration.py <file_path>')
+        sys.exit(1)
+
+    filename = os.path.basename(file_path)
+
+    # Determine file type and validate
+    try:
+        with open(file_path, 'r', encoding='utf-8') as f:
+            content = f.read()
+    except Exception as e:
+        print(f'Error reading file: {e}')
+        sys.exit(1)
+
+    # Skip if file is too small (likely not a real integration file)
+    if len(content) < 50:
+        sys.exit(0)
+
+    # Skip template files (contain placeholders)
+    if '{{' in content and '}}' in content:
+        print(f'ℹ️ Skipping template file: {filename}')
+        sys.exit(0)
+
+    # Validate based on file type
+    if APEX_PATTERN.search(filename):
+        # Only validate if it looks like integration code
+        if any(keyword in content for keyword in ['HttpRequest', 'Http(', 'callout:', 'EventBus', 'ChangeEvent']):
+            validate_apex_file(content, filename)
+            print_score_report(filename)
+    elif NAMED_CRED_PATTERN.search(filename):
+        validate_named_credential(content)
+        print_score_report(filename)
+    elif '__e.object-meta.xml' in filename:
+        validate_platform_event(content)
+        print_score_report(filename)
+    else:
+        # Not an integration file we validate
+        sys.exit(0)
+
+
+if __name__ == '__main__':
+    main()