@salesforce/afv-skills 1.8.0 → 1.9.1

package/skills/generating-visual-diagrams/scripts/check-prerequisites.sh

@@ -0,0 +1,101 @@
+#!/bin/bash
+# check-prerequisites.sh - Verify generating-visual-diagrams requirements before use
+# Returns 0 if all required checks pass, 1 if any required fail
+
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
+GRAY='\033[0;90m'
+NC='\033[0m'
+
+ERRORS=0
+WARNINGS=0
+
+echo ""
+echo -e "${BLUE}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
+echo -e "${BLUE}  📸 SF-IMAGEN PREREQUISITES CHECK${NC}"
+echo -e "${BLUE}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
+echo ""
+echo -e "${GRAY}  REQUIRED:${NC}"
+
+# Check 1: macOS (required for Preview app)
+echo -n "  Checking macOS (for Preview app)... "
+if [[ "$OSTYPE" == "darwin"* ]]; then
+    echo -e "${GREEN}✓ macOS detected${NC}"
+else
+    echo -e "${RED}✗ Not macOS${NC}"
+    echo -e "    ${YELLOW}→ generating-visual-diagrams uses macOS Preview app for image display${NC}"
+    echo -e "    ${YELLOW}→ Current OS: $OSTYPE${NC}"
+    ERRORS=$((ERRORS + 1))
+fi
+
+# Check 2: Gemini API Key
+echo -n "  Checking GEMINI_API_KEY... "
+if [[ -n "$GEMINI_API_KEY" ]]; then
+    # Mask the key for display
+    MASKED_KEY="${GEMINI_API_KEY:0:10}...${GEMINI_API_KEY: -4}"
+    echo -e "${GREEN}✓ Set ($MASKED_KEY)${NC}"
+else
+    echo -e "${RED}✗ Not set${NC}"
+    echo -e "    ${YELLOW}→ Nano Banana Pro requires a personal API key${NC}"
+    echo -e "    ${YELLOW}→ Get one at: https://aistudio.google.com/apikey${NC}"
+    echo -e "    ${YELLOW}→ Add to ~/.zshrc: export GEMINI_API_KEY=\"your-key\"${NC}"
+    ERRORS=$((ERRORS + 1))
+fi
+
+# Check 3: Gemini CLI
+echo -n "  Checking Gemini CLI... "
+if command -v gemini &> /dev/null; then
+    GEMINI_VERSION=$(gemini --version 2>/dev/null | head -1 || echo "installed")
+    echo -e "${GREEN}✓ $GEMINI_VERSION${NC}"
+else
+    echo -e "${RED}✗ Not installed${NC}"
+    echo -e "    ${YELLOW}→ Install: npm install -g @google/gemini-cli${NC}"
+    ERRORS=$((ERRORS + 1))
+fi
+
+# Check 4: Nano Banana Extension
+echo -n "  Checking Nano Banana extension... "
+if gemini extensions list 2>/dev/null | grep -q "nanobanana"; then
+    echo -e "${GREEN}✓ Installed${NC}"
+else
+    echo -e "${RED}✗ Not installed${NC}"
+    echo -e "    ${YELLOW}→ Install: gemini extensions install nanobanana${NC}"
+    ERRORS=$((ERRORS + 1))
+fi
+
+echo ""
+echo -e "${GRAY}  OPTIONAL (for 4K/editing via Python script):${NC}"
+
+# Check 5: uv (optional, for Python script)
+echo -n "  Checking uv (Python runner)... "
+if command -v uv &> /dev/null; then
+    UV_VERSION=$(uv --version 2>&1 | head -1)
+    echo -e "${GREEN}✓ $UV_VERSION${NC}"
+else
+    echo -e "${YELLOW}○ Not installed (optional)${NC}"
+    echo -e "    ${GRAY}→ For 4K resolution/editing: curl -LsSf https://astral.sh/uv/install.sh | sh${NC}"
+    WARNINGS=$((WARNINGS + 1))
+fi
+
+echo ""
+echo -e "${BLUE}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
+
+if [[ $ERRORS -eq 0 ]]; then
+    if [[ $WARNINGS -gt 0 ]]; then
+        echo -e "  ${GREEN}✅ All required prerequisites met!${NC}"
+        echo -e "  ${YELLOW}⚠️  $WARNINGS optional feature(s) unavailable${NC}"
+    else
+        echo -e "  ${GREEN}✅ All prerequisites met! generating-visual-diagrams is ready to use.${NC}"
+    fi
+    echo -e "${BLUE}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
+    echo ""
+    exit 0
+else
+    echo -e "  ${RED}❌ $ERRORS required prerequisite(s) missing.${NC}"
+    echo -e "  ${RED}   Please fix before using generating-visual-diagrams.${NC}"
+    echo -e "${BLUE}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
+    echo ""
+    exit 1
+fi

package/skills/generating-visual-diagrams/scripts/generate_image.py

@@ -0,0 +1,243 @@
+#!/usr/bin/env python3
+# /// script
+# requires-python = ">=3.10"
+# dependencies = ["google-genai>=1.0.0", "pillow>=10.0.0"]
+# ///
+"""
+Direct Gemini API image generation with resolution control.
+
+This script complements the CLI extension for power features:
+- Resolution control: 1K (draft), 2K (medium), 4K (production)
+- Image editing: Modify existing images with natural language
+- Timestamp filenames: Automatic versioning for iteration tracking
+
+Usage:
+  # Generate new image at 1K (draft)
+  uv run scripts/generate_image.py -p "Salesforce ERD diagram..." -f "account-erd.png"
+
+  # Generate at 4K (production)
+  uv run scripts/generate_image.py -p "Salesforce ERD diagram..." -f "account-erd.png" -r 4K
+
+  # Edit existing image
+  uv run scripts/generate_image.py -p "Add a legend in bottom right" -i input.png -f "output.png"
+
+Workflow: Draft → Iterate → Final
+  1. Generate at 1K for quick feedback (~3s)
+  2. Refine prompt until layout/content is correct
+  3. Generate final at 4K for production quality (~10s)
+
+License: MIT
+"""
+
+import argparse
+import os
+import subprocess
+import sys
+from datetime import datetime
+from io import BytesIO
+from pathlib import Path
+
+try:
+    from google import genai
+    from google.genai import types
+    from PIL import Image
+except ImportError as e:
+    print(f"Error: Missing dependency - {e}")
+    print("Run with: uv run scripts/generate_image.py ...")
+    sys.exit(1)
+
+
+# Resolution mapping (uppercase K required by API!)
+RESOLUTIONS = {
+    "1K": "1K",   # ~1024px - drafts, fast iteration
+    "2K": "2K",   # ~2048px - medium quality
+    "4K": "4K",   # ~4096px - production quality
+}
+
+# Default output directory (matches CLI extension)
+OUTPUT_DIR = Path.home() / "nanobanana-output"
+
+
+def get_auto_resolution(image_path: str) -> str:
+    """Auto-detect resolution based on input image dimensions."""
+    try:
+        with Image.open(image_path) as img:
+            max_dim = max(img.width, img.height)
+            if max_dim < 1500:
+                return "1K"
+            elif max_dim < 3000:
+                return "2K"
+            else:
+                return "4K"
+    except Exception:
+        return "1K"
+
+
+def generate_image(
+    prompt: str,
+    filename: str,
+    resolution: str = "1K",
+    input_image: str | None = None,
+    api_key: str | None = None,
+    aspect_ratio: str | None = None,
+) -> str:
+    """Generate or edit an image using Gemini 3 Pro Image API.
+
+    Args:
+        prompt: Text description for generation or editing instruction
+        filename: Output filename (timestamp will be prepended)
+        resolution: Output resolution - 1K, 2K, or 4K (uppercase required!)
+        input_image: Path to existing image for editing (optional)
+        api_key: Gemini API key (falls back to GEMINI_API_KEY env var)
+        aspect_ratio: Aspect ratio like "16:9", "1:1", "4:3" (optional)
+
+    Returns:
+        Path to saved image file
+    """
+    # Get API key
+    api_key = api_key or os.environ.get("GEMINI_API_KEY")
+    if not api_key:
+        raise ValueError(
+            "GEMINI_API_KEY not found. Set it in ~/.zshrc or pass via --api-key"
+        )
+
+    # Initialize client
+    client = genai.Client(api_key=api_key)
+
+    # Build contents (image first if editing, then prompt)
+    contents = []
+    if input_image:
+        img = Image.open(input_image)
+        # Convert RGBA to RGB if needed
+        if img.mode == "RGBA":
+            background = Image.new("RGB", img.size, (255, 255, 255))
+            background.paste(img, mask=img.split()[3])
+            img = background
+        contents.append(img)
+
+        # Auto-detect resolution for editing if not specified
+        if resolution == "1K":
+            resolution = get_auto_resolution(input_image)
+            print(f"Auto-detected resolution: {resolution}")
+
+    contents.append(prompt)
+
+    # Build image config
+    image_config_kwargs = {"image_size": RESOLUTIONS[resolution]}
+    if aspect_ratio:
+        image_config_kwargs["aspect_ratio"] = aspect_ratio
+
+    # Generate with resolution config
+    print(f"Generating at {resolution} resolution...")
+    response = client.models.generate_content(
+        model="gemini-3-pro-image-preview",
+        contents=contents,
+        config=types.GenerateContentConfig(
+            response_modalities=["IMAGE", "TEXT"],
+            image_config=types.ImageConfig(**image_config_kwargs),
+        ),
+    )
+
+    # Save output with timestamp filename
+    OUTPUT_DIR.mkdir(exist_ok=True)
+    timestamp = datetime.now().strftime("%Y-%m-%d-%H-%M-%S")
+
+    # Clean filename (remove extension if present, we'll add .png)
+    clean_name = Path(filename).stem
+    output_filename = f"{timestamp}-{clean_name}.png"
+    output_path = OUTPUT_DIR / output_filename
+
+    # Extract and save image from response
+    for part in response.candidates[0].content.parts:
+        if hasattr(part, "inline_data") and part.inline_data:
+            img = Image.open(BytesIO(part.inline_data.data))
+            # Convert to RGB if needed
+            if img.mode == "RGBA":
+                background = Image.new("RGB", img.size, (255, 255, 255))
+                background.paste(img, mask=img.split()[3])
+                img = background
+            img.save(output_path, "PNG")
+            return str(output_path)
+
+    raise RuntimeError("No image data in response")
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Generate images with Gemini 3 Pro Image API",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Examples:
+  # Draft (fast, cheap)
+  uv run generate_image.py -p "Account ERD diagram" -f "account-erd.png"
+
+  # Production (4K)
+  uv run generate_image.py -p "Account ERD diagram" -f "account-erd.png" -r 4K
+
+  # Edit existing image
+  uv run generate_image.py -p "Add legend" -i prev.png -f "updated.png"
+
+  # With aspect ratio
+  uv run generate_image.py -p "Dashboard mockup" -f "dash.png" -a "16:9"
+        """,
+    )
+    parser.add_argument(
+        "-p", "--prompt",
+        required=True,
+        help="Image description or editing instruction",
+    )
+    parser.add_argument(
+        "-f", "--filename",
+        required=True,
+        help="Output filename (timestamp auto-prepended)",
+    )
+    parser.add_argument(
+        "-r", "--resolution",
+        choices=["1K", "2K", "4K"],
+        default="1K",
+        help="Output resolution (default: 1K for drafts)",
+    )
+    parser.add_argument(
+        "-i", "--input-image",
+        help="Path to existing image for editing",
+    )
+    parser.add_argument(
+        "-k", "--api-key",
+        help="Gemini API key (defaults to GEMINI_API_KEY env var)",
+    )
+    parser.add_argument(
+        "-a", "--aspect-ratio",
+        help="Aspect ratio (e.g., '16:9', '1:1', '4:3')",
+    )
+    parser.add_argument(
+        "--no-open",
+        action="store_true",
+        help="Don't auto-open the image in Preview after generation",
+    )
+
+    args = parser.parse_args()
+
+    try:
+        output_path = generate_image(
+            prompt=args.prompt,
+            filename=args.filename,
+            resolution=args.resolution,
+            input_image=args.input_image,
+            api_key=args.api_key,
+            aspect_ratio=args.aspect_ratio,
+        )
+        print(f"✅ Saved: {output_path}")
+
+        # Auto-open in macOS Preview unless --no-open is specified
+        if not args.no_open:
+            subprocess.run(["open", output_path], check=False)
+            print(f"   📸 Opened in Preview")
+        else:
+            print(f"   Open with: open {output_path}")
+    except Exception as e:
+        print(f"❌ Error: {e}")
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

package/skills/handling-sf-data/CREDITS.md

@@ -0,0 +1,5 @@
+# Credits & Acknowledgments
+
+This skill is built on established Salesforce data, SOQL, and bulk operation patterns from the Salesforce platform ecosystem.
+
+---

package/skills/handling-sf-data/README.md

@@ -0,0 +1,112 @@
+# handling-sf-data
+
+Salesforce data operations skill for Claude Code. Create, validate, bulk-load, clean up, and troubleshoot org data with a describe-first workflow.
+
+## Features
+
+- **CRUD Operations**: Create, read, update, delete records via sf CLI
+- **Describe-First Validation**: Inspect required fields, picklists, and createable fields before data creation
+- **CLI-First Test Data**: Prefer `sf data` commands for straightforward seed data
+- **Bulk Operations**: Import/export via Bulk API 2.0
+- **Record Tracking & Cleanup**: Savepoint/rollback, cleanup scripts, delete-by-pattern workflows
+- **130-Point Validation**: Automated scoring across 7 categories
+
+## Installation
+
+Add the skill to your Cursor project by placing the `handling-sf-data` directory under your `skills/` folder and enabling it in your agent configuration.
+
+## Usage
+
+Invoke the skill:
+```
+Skill(skill="handling-sf-data")
+Request: "Create 251 test Account records with varying Industries for trigger testing in org dev"
+```
+
+### Common Operations
+
+| Operation | Example Request |
+|-----------|-----------------|
+| Query | "Query all Accounts with related Contacts in org dev" |
+| Create | "Create 10 test Opportunities at various stages" |
+| Bulk Insert | "Insert 500 accounts from accounts.csv" |
+| Update | "Update Account 001xxx with new Industry" |
+| Delete | "Delete all test records with Name LIKE 'Test%'" |
+| Cleanup | "Generate cleanup script for all records created today" |
+
+## Recommended workflow
+
+1. Describe the target object when schema constraints are uncertain
+2. Validate required fields, picklist values, and createable fields
+3. Choose CLI, tree import, bulk import, or anonymous Apex intentionally
+4. Verify results and provide cleanup instructions
+
+## Validation Scoring (130 Points)
+
+| Category | Points | Focus |
+|----------|--------|-------|
+| Query Efficiency | 25 | SOQL selectivity, indexed fields, no N+1 |
+| Bulk Safety | 25 | Governor limits, batch sizing |
+| Data Integrity | 20 | Required fields, relationships |
+| Security & FLS | 20 | Field-level security, no PII |
+| Test Patterns | 15 | 200+ records, edge cases |
+| Cleanup & Isolation | 15 | Rollback, cleanup scripts |
+| Documentation | 10 | Purpose, expected outcomes |
+
+## Cross-Skill Integration
+
+### With deploying-metadata
+```
+Skill(skill="deploying-metadata")
+Request: "Describe Invoice__c in org dev - show all fields"
+```
+Then use handling-sf-data with accurate field names and permitted values.
+
+### From generating-apex / generating-flow
+```
+Skill(skill="handling-sf-data")
+Request: "Create 251 test Accounts to trigger AccountTrigger bulk testing"
+```
+
+## Directory Structure
+
+```
+handling-sf-data/
+├── SKILL.md                   # Main skill prompt
+├── assets/
+│   ├── factories/             # Apex test data factories
+│   ├── soql/                  # SOQL query templates
+│   ├── bulk/                  # Bulk operation templates
+│   ├── csv/                   # CSV import templates
+│   ├── json/                  # JSON tree templates
+│   └── cleanup/               # Cleanup scripts
+├── scripts/                   # Pre-flight validation scripts
+└── references/                # Documentation and examples
+```
+
+## Key documentation
+
+- [SKILL.md](SKILL.md) - Full workflow and orchestration guidance
+- [references/test-data-best-practices.md](references/test-data-best-practices.md) - Describe-first validation and retry strategy
+- [references/sf-cli-data-commands.md](references/sf-cli-data-commands.md) - sf CLI command patterns
+- [references/cleanup-rollback-guide.md](references/cleanup-rollback-guide.md) - Cleanup strategies
+
+## sf CLI Commands Wrapped
+
+| Operation | Command |
+|-----------|---------|
+| Query | `sf data query --query "..." --target-org [alias]` |
+| Create | `sf data create record --sobject [Object] --values "..."` |
+| Update | `sf data update record --sobject [Object] --record-id [Id] --values "..."` |
+| Delete | `sf data delete record --sobject [Object] --record-id [Id]` |
+| Bulk Import | `sf data import bulk --file [csv] --sobject [Object]` |
+| Bulk Delete | `sf data delete bulk --file [csv] --sobject [Object]` |
+| Tree Export | `sf data export tree --query "..." --output-dir [dir]` |
+| Tree Import | `sf data import tree --files [json]` |
+| Apex Run | `sf apex run --file [script.apex]` |
+
+## Requirements
+
+- sf CLI v2
+- Target Salesforce org (sandbox or production)
+- Claude Code with skill plugins enabled