@salesforce/afv-skills 1.7.5 → 1.9.0

package/skills/querying-soql/references/soql-syntax-reference.md

@@ -0,0 +1,208 @@
+<!-- Parent: querying-soql/SKILL.md -->
+
+# SOQL Syntax Reference
+
+## Basic Query Structure
+
+```sql
+SELECT field1, field2, ...
+FROM ObjectName
+WHERE condition1 AND condition2
+ORDER BY field1 ASC/DESC
+LIMIT number
+OFFSET number
+```
+
+### Field Selection
+
+```sql
+-- Specific fields (recommended)
+SELECT Id, Name, Industry FROM Account
+
+-- All fields (avoid in Apex - use only in Developer Console)
+SELECT FIELDS(ALL) FROM Account LIMIT 200
+
+-- Standard fields only
+SELECT FIELDS(STANDARD) FROM Account
+```
+
+### WHERE Clause Operators
+
+| Operator | Example | Notes |
+|----------|---------|-------|
+| `=` | `Name = 'Acme'` | Exact match |
+| `!=` | `Status != 'Closed'` | Not equal |
+| `<`, `>`, `<=`, `>=` | `Amount > 1000` | Comparison |
+| `LIKE` | `Name LIKE 'Acme%'` | Wildcard match |
+| `IN` | `Status IN ('New', 'Open')` | Multiple values |
+| `NOT IN` | `Type NOT IN ('Other')` | Exclude values |
+| `INCLUDES` | `Interests__c INCLUDES ('Golf')` | Multi-select picklist |
+| `EXCLUDES` | `Interests__c EXCLUDES ('Golf')` | Multi-select exclude |
+
+### Date Literals
+
+| Literal | Meaning |
+|---------|---------|
+| `TODAY` | Current day |
+| `YESTERDAY` | Previous day |
+| `THIS_WEEK` | Current week (Sun-Sat) |
+| `LAST_WEEK` | Previous week |
+| `THIS_MONTH` | Current month |
+| `LAST_MONTH` | Previous month |
+| `THIS_QUARTER` | Current quarter |
+| `THIS_YEAR` | Current year |
+| `LAST_N_DAYS:n` | Last n days |
+| `NEXT_N_DAYS:n` | Next n days |
+
+```sql
+-- Created in last 30 days
+SELECT Id FROM Account WHERE CreatedDate = LAST_N_DAYS:30
+
+-- Modified this month
+SELECT Id FROM Contact WHERE LastModifiedDate = THIS_MONTH
+```
+
+---
+
+## Relationship Queries
+
+### Child-to-Parent (Dot Notation)
+
+```sql
+-- Access parent fields
+SELECT Id, Name, Account.Name, Account.Industry
+FROM Contact
+WHERE Account.AnnualRevenue > 1000000
+
+-- Up to 5 levels
+SELECT Id, Contact.Account.Owner.Manager.Name
+FROM Case
+```
+
+### Parent-to-Child (Subquery)
+
+```sql
+-- Get parent with related children
+SELECT Id, Name,
+       (SELECT Id, FirstName, LastName FROM Contacts),
+       (SELECT Id, Name, Amount FROM Opportunities WHERE StageName = 'Closed Won')
+FROM Account
+WHERE Industry = 'Technology'
+```
+
+### Standard Relationship Names
+
+| Object | Relationship Name | Example |
+|--------|-------------------|---------|
+| Account → Contacts | `Contacts` | `(SELECT Id FROM Contacts)` |
+| Account → Opportunities | `Opportunities` | `(SELECT Id FROM Opportunities)` |
+| Account → Cases | `Cases` | `(SELECT Id FROM Cases)` |
+| Contact → Cases | `Cases` | `(SELECT Id FROM Cases)` |
+| Opportunity → OpportunityLineItems | `OpportunityLineItems` | `(SELECT Id FROM OpportunityLineItems)` |
+
+### Custom Object Relationships
+
+```sql
+-- Custom relationship: add __r suffix
+SELECT Id, Name, Custom_Object__r.Name
+FROM Another_Object__c
+
+-- Child relationship: add __r suffix
+SELECT Id, (SELECT Id FROM Custom_Children__r)
+FROM Parent_Object__c
+```
+
+---
+
+## Aggregate Queries
+
+### Basic Aggregates
+
+```sql
+-- Count all records
+SELECT COUNT() FROM Account
+
+-- Count with alias
+SELECT COUNT(Id) cnt FROM Account
+
+-- Sum, Average, Min, Max
+SELECT SUM(Amount), AVG(Amount), MIN(Amount), MAX(Amount)
+FROM Opportunity
+WHERE StageName = 'Closed Won'
+```
+
+### GROUP BY
+
+```sql
+-- Count by field
+SELECT Industry, COUNT(Id)
+FROM Account
+GROUP BY Industry
+
+-- Multiple groupings
+SELECT StageName, CALENDAR_YEAR(CloseDate), COUNT(Id)
+FROM Opportunity
+GROUP BY StageName, CALENDAR_YEAR(CloseDate)
+```
+
+### HAVING Clause
+
+```sql
+-- Filter aggregated results
+SELECT Industry, COUNT(Id) cnt
+FROM Account
+GROUP BY Industry
+HAVING COUNT(Id) > 10
+```
+
+### GROUP BY ROLLUP
+
+```sql
+-- Subtotals
+SELECT LeadSource, Rating, COUNT(Id)
+FROM Lead
+GROUP BY ROLLUP(LeadSource, Rating)
+```
+
+---
+
+## Advanced Features
+
+### Polymorphic Relationships (What)
+
+```sql
+-- Query polymorphic fields
+SELECT Id, What.Name, What.Type
+FROM Task
+WHERE What.Type IN ('Account', 'Opportunity')
+
+-- TYPEOF for conditional fields
+SELECT
+    TYPEOF What
+        WHEN Account THEN Name, Phone
+        WHEN Opportunity THEN Name, Amount
+    END
+FROM Task
+```
+
+### Semi-Joins and Anti-Joins
+
+```sql
+-- Semi-join: Records that HAVE related records
+SELECT Id, Name FROM Account
+WHERE Id IN (SELECT AccountId FROM Contact)
+
+-- Anti-join: Records that DON'T HAVE related records
+SELECT Id, Name FROM Account
+WHERE Id NOT IN (SELECT AccountId FROM Opportunity)
+```
+
+### Format and Currency
+
+```sql
+-- Format currency/date in results
+SELECT FORMAT(Amount), FORMAT(CloseDate) FROM Opportunity
+
+-- Convert to user's currency
+SELECT Id, convertCurrency(Amount) FROM Opportunity
+```

package/skills/querying-soql/scripts/post-tool-validate.py

@@ -0,0 +1,322 @@
+#!/usr/bin/env python3
+"""
+Post-Tool Validation Hook for querying-soql skill.
+
+This hook runs AFTER Write or Edit tool completes and provides validation
+feedback for SOQL files (*.soql).
+
+Integrates:
+1. Static SOQL validation (syntax, best practices)
+2. Live Query Plan Analysis (if org connected)
+
+Hook Input (stdin): JSON with tool_input and tool_response
+Hook Output (stdout): JSON with optional output message
+
+This hook is ADVISORY - it provides feedback but does not block operations.
+"""
+
+import sys
+import os
+import json
+
+# Add script directory to path for imports
+SCRIPT_DIR = os.path.dirname(os.path.abspath(__file__))
+sys.path.insert(0, SCRIPT_DIR)
+
+# Find shared modules (../../shared relative to querying-soql)
+PLUGIN_ROOT = os.path.dirname(os.path.dirname(SCRIPT_DIR))  # querying-soql/
+SKILLS_ROOT = os.path.dirname(PLUGIN_ROOT)  # sf-skills/
+SHARED_DIR = os.path.join(SKILLS_ROOT, "shared")
+sys.path.insert(0, SHARED_DIR)
+
+
+def validate_soql_file(file_path: str) -> dict:
+    """
+    Validate a .soql file with static analysis and live query plan.
+
+    Args:
+        file_path: Path to .soql file
+
+    Returns:
+        dict with validation results and output message
+    """
+    output_parts = []
+    file_name = os.path.basename(file_path)
+    issues = []
+    recommendations = []
+
+    try:
+        # Read file content
+        with open(file_path, 'r') as f:
+            content = f.read()
+
+        if not content.strip():
+            return {"continue": True}
+
+        # ═══════════════════════════════════════════════════════════════════
+        # PHASE 1: Static SOQL Validation
+        # ═══════════════════════════════════════════════════════════════════
+        static_result = validate_soql_static(content)
+        issues.extend(static_result.get('issues', []))
+        recommendations.extend(static_result.get('recommendations', []))
+
+        # ═══════════════════════════════════════════════════════════════════
+        # PHASE 2: Live Query Plan Analysis (if org connected)
+        # ═══════════════════════════════════════════════════════════════════
+        live_result = None
+        org_name = None
+
+        try:
+            from code_analyzer.live_query_plan import LiveQueryPlanAnalyzer
+
+            analyzer = LiveQueryPlanAnalyzer()
+            if analyzer.is_org_available():
+                org_name = analyzer.get_target_org()
+                live_result = analyzer.analyze(content)
+
+                if live_result.success:
+                    # Add live plan insights as issues/recommendations
+                    if not live_result.is_selective:
+                        issues.append({
+                            'severity': 'WARNING',
+                            'message': f'Non-selective query (cost: {live_result.relative_cost:.1f})',
+                            'source': 'LivePlan'
+                        })
+
+                    # Add notes as recommendations
+                    for note in live_result.notes:
+                        recommendations.append(str(note))
+
+                    # Get optimization suggestions
+                    suggestions = analyzer.get_optimization_suggestions(live_result)
+                    recommendations.extend(suggestions)
+
+        except ImportError:
+            pass  # Live analysis not available
+        except Exception as e:
+            pass  # Don't fail on live analysis errors
+
+        # ═══════════════════════════════════════════════════════════════════
+        # PHASE 3: Format Output
+        # ═══════════════════════════════════════════════════════════════════
+        output_parts.append("")
+        output_parts.append(f"🔍 SOQL Validation: {file_name}")
+        output_parts.append("═" * 55)
+
+        # Static analysis summary
+        if static_result.get('has_where_clause'):
+            output_parts.append("✅ Has WHERE clause")
+        else:
+            output_parts.append("⚠️ Missing WHERE clause")
+
+        if static_result.get('has_limit'):
+            output_parts.append("✅ Has LIMIT clause")
+        else:
+            output_parts.append("⚠️ Missing LIMIT clause")
+
+        if static_result.get('has_hardcoded_ids'):
+            output_parts.append("⚠️ Contains hardcoded IDs")
+
+        # Live Query Plan section
+        output_parts.append("")
+        if live_result and live_result.success:
+            output_parts.append(f"🌐 Live Query Plan Analysis")
+            output_parts.append(f"   Org: {org_name}")
+            output_parts.append(f"   {live_result.icon} Selective: {live_result.is_selective}")
+            output_parts.append(f"   📊 Relative Cost: {live_result.relative_cost:.2f} ({live_result.selectivity_rating})")
+            output_parts.append(f"   📈 Operation: {live_result.leading_operation}")
+
+            if live_result.cardinality > 0:
+                output_parts.append(f"   📋 Cardinality: {live_result.cardinality:,} / {live_result.sobject_cardinality:,}")
+
+            if live_result.notes:
+                output_parts.append("")
+                output_parts.append("   📝 Query Plan Notes:")
+                for note in live_result.notes[:3]:
+                    output_parts.append(f"      • {str(note)[:70]}")
+        elif org_name is None:
+            output_parts.append("🌐 Live Query Plan: No org connected")
+            output_parts.append("   Run 'sf org login web' to enable live analysis")
+        elif live_result and not live_result.success:
+            output_parts.append(f"🌐 Live Query Plan: Error")
+            output_parts.append(f"   {live_result.error[:60]}")
+
+        # Issues
+        if issues:
+            output_parts.append("")
+            output_parts.append(f"⚠️ Issues ({len(issues)}):")
+            severity_icons = {
+                'CRITICAL': '🔴', 'HIGH': '🟠', 'MODERATE': '🟡',
+                'WARNING': '⚠️', 'LOW': '🔵', 'INFO': 'ℹ️'
+            }
+            for issue in issues[:5]:
+                icon = severity_icons.get(issue.get('severity', 'INFO'), 'ℹ️')
+                source = f"[{issue.get('source', '')}]" if issue.get('source') else ""
+                output_parts.append(f"   {icon} {source} {issue.get('message', '')[:60]}")
+
+        # Recommendations
+        unique_recs = list(dict.fromkeys(recommendations))  # Remove duplicates
+        if unique_recs:
+            output_parts.append("")
+            output_parts.append("💡 Recommendations:")
+            for rec in unique_recs[:5]:
+                output_parts.append(f"   • {rec[:65]}")
+
+        output_parts.append("═" * 55)
+
+        return {
+            "continue": True,
+            "output": "\n".join(output_parts)
+        }
+
+    except Exception as e:
+        return {
+            "continue": True,
+            "output": f"⚠️ SOQL validation error: {e}"
+        }
+
+
+def validate_soql_static(content: str) -> dict:
+    """
+    Perform static validation on SOQL content.
+
+    Args:
+        content: SOQL query string
+
+    Returns:
+        dict with validation flags and issues
+    """
+    import re
+
+    result = {
+        'is_valid': True,
+        'has_where_clause': False,
+        'has_limit': False,
+        'has_order_by': False,
+        'has_hardcoded_ids': False,
+        'uses_indexed_fields': False,
+        'issues': [],
+        'recommendations': []
+    }
+
+    # Remove comments
+    clean = re.sub(r'--.*$', '', content, flags=re.MULTILINE)
+    clean = re.sub(r'//.*$', '', clean, flags=re.MULTILINE)
+    clean = re.sub(r'/\*[\s\S]*?\*/', '', clean)
+
+    # Check for WHERE clause
+    result['has_where_clause'] = bool(re.search(r'\bWHERE\b', clean, re.IGNORECASE))
+
+    # Check for LIMIT
+    result['has_limit'] = bool(re.search(r'\bLIMIT\s+\d+', clean, re.IGNORECASE))
+
+    # Check for ORDER BY
+    result['has_order_by'] = bool(re.search(r'\bORDER\s+BY\b', clean, re.IGNORECASE))
+
+    # Check for hardcoded IDs (15 or 18 char alphanumeric in quotes)
+    result['has_hardcoded_ids'] = bool(
+        re.search(r"'[a-zA-Z0-9]{15}'", clean) or
+        re.search(r"'[a-zA-Z0-9]{18}'", clean)
+    )
+
+    # Check for indexed fields in WHERE
+    indexed_fields = ['Id', 'Name', 'OwnerId', 'CreatedDate', 'LastModifiedDate', 'RecordTypeId']
+    where_match = re.search(r'\bWHERE\b(.*?)(?:\bORDER\b|\bGROUP\b|\bLIMIT\b|$)', clean, re.IGNORECASE | re.DOTALL)
+    if where_match:
+        where_clause = where_match.group(1)
+        for field in indexed_fields:
+            if re.search(rf'\b{field}\b', where_clause, re.IGNORECASE):
+                result['uses_indexed_fields'] = True
+                break
+
+    # Syntax validation
+    # Check for SELECT without FROM
+    if re.search(r'\bSELECT\b', clean, re.IGNORECASE):
+        if not re.search(r'\bFROM\b', clean, re.IGNORECASE):
+            result['issues'].append({
+                'severity': 'HIGH',
+                'message': 'SELECT statement missing FROM clause'
+            })
+            result['is_valid'] = False
+
+    # Check for SELECT *
+    if re.search(r'\bSELECT\s+\*', clean, re.IGNORECASE):
+        result['issues'].append({
+            'severity': 'HIGH',
+            'message': 'SELECT * is not valid in SOQL - specify field names'
+        })
+        result['is_valid'] = False
+
+    # Check for == instead of =
+    if re.search(r'==', clean):
+        result['issues'].append({
+            'severity': 'HIGH',
+            'message': 'Invalid operator "==" - use "=" in SOQL'
+        })
+
+    # Check for unbalanced parentheses
+    if clean.count('(') != clean.count(')'):
+        result['issues'].append({
+            'severity': 'HIGH',
+            'message': 'Unbalanced parentheses'
+        })
+
+    # Add recommendations
+    if not result['has_where_clause']:
+        result['recommendations'].append('Add WHERE clause for better query selectivity')
+
+    if not result['has_limit']:
+        result['recommendations'].append('Add LIMIT clause to prevent large result sets')
+
+    if result['has_hardcoded_ids']:
+        result['recommendations'].append('Avoid hardcoded IDs - use bind variables instead')
+
+    if result['has_where_clause'] and not result['uses_indexed_fields']:
+        result['recommendations'].append('Add an indexed field (Id, Name, CreatedDate) to WHERE for better performance')
+
+    return result
+
+
+def main():
+    """
+    Main hook entry point.
+
+    Reads hook input from stdin, validates SOQL files.
+    """
+    try:
+        # Read hook input from stdin
+        hook_input = json.load(sys.stdin)
+
+        # Extract file path from tool input
+        tool_input = hook_input.get("tool_input", {})
+        file_path = tool_input.get("file_path", "")
+
+        # Check if operation was successful
+        tool_response = hook_input.get("tool_response", {})
+        if not tool_response.get("success", True):
+            print(json.dumps({"continue": True}))
+            return 0
+
+        # Only validate .soql files
+        result = {"continue": True}
+
+        if file_path.lower().endswith(".soql"):
+            result = validate_soql_file(file_path)
+
+        # Output result
+        print(json.dumps(result))
+        return 0
+
+    except json.JSONDecodeError:
+        print(json.dumps({"continue": True}))
+        return 0
+    except Exception as e:
+        print(json.dumps({
+            "continue": True,
+            "output": f"⚠️ Hook error: {e}"
+        }))
+        return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/skills/retrieving-datacloud/CREDITS.md

@@ -0,0 +1,7 @@
+# Credits & Acknowledgments
+
+Primary contributor: **Gnanasekaran Thoppae**
+
+This skill is part of the `*-datacloud` family. Shared attribution, upstream source mapping, and maintenance notes live in:
+- [../orchestrating-datacloud/CREDITS.md](../orchestrating-datacloud/CREDITS.md)
+- [../orchestrating-datacloud/UPSTREAM.md](../orchestrating-datacloud/UPSTREAM.md)

package/skills/retrieving-datacloud/README.md

@@ -0,0 +1,44 @@
+# retrieving-datacloud
+
+Query and search workflows for Salesforce Data Cloud.
+
+## Use this skill for
+
+- quick SQL counts
+- paginated SQL (`sqlv2`)
+- async query lifecycles
+- table describe
+- vector search
+- hybrid search with optional prefilter
+- search index inspection and lifecycle work
+
+## Example requests
+
+```text
+"Run a Data Cloud SQL query against unified profiles"
+"Describe this Data Cloud table before I write SQL"
+"Help me troubleshoot vector search in Data Cloud"
+"Run a hybrid search with a prefilter in Data Cloud"
+"Create and inspect a search index"
+```
+
+## Common commands
+
+```bash
+sf data360 query sql -o myorg --sql 'SELECT COUNT(*) FROM "ssot__Individual__dlm"' 2>/dev/null
+sf data360 query describe -o myorg --table ssot__Individual__dlm 2>/dev/null
+sf data360 search-index list -o myorg 2>/dev/null
+sf data360 query vector -o myorg --index Knowledge_Index --query "reset password" --limit 5 2>/dev/null
+sf data360 query hybrid -o myorg --index Knowledge_Index --query "reset password" --limit 5 2>/dev/null
+```
+
+## Example payloads
+
+- [examples/search-indexes/vector-knowledge.json](examples/search-indexes/vector-knowledge.json)
+- [examples/search-indexes/hybrid-structured.json](examples/search-indexes/hybrid-structured.json)
+
+## References
+
+- [SKILL.md](SKILL.md)
+- [../orchestrating-datacloud/assets/definitions/search-index.template.json](../orchestrating-datacloud/assets/definitions/search-index.template.json)
+- [CREDITS.md](CREDITS.md)