action.yml

name: "Setup Salesforce CLI"
description: "Enterprise-grade Salesforce CLI setup with authentication, caching, and optional tooling"
author: "Ryan Bumstead"

branding:
  icon: "zap"
  color: "blue"

inputs:
  # ============================================================================
  # CORE RUNTIME
  # ============================================================================
  node_version:
    description: "Node.js version"
    required: false
    default: "20"

  cli_version:
    description: "Salesforce CLI version (latest or explicit version like 2.x.x)"
    required: false
    default: "latest"

  cli_version_for_cache:
    description: "CLI version granularity for cache key (major, minor, or exact). Controls cache reuse vs freshness."
    required: false
    default: "minor"

  strict:
    description: "Fail pipeline on optional tool installation errors"
    required: false
    default: "false"

  dry_run:
    description: "Dry-run mode: skip authentication and mutations, validate detection only"
    required: false
    default: "false"

  debug:
    description: "Enable verbose debug output for troubleshooting"
    required: false
    default: "false"

  # ============================================================================
  # AUTHENTICATION
  # ============================================================================
  skip_auth:
    description: "Skip authentication (CLI installation only)"
    required: false
    default: "false"

  auth_method:
    description: "Authentication method: 'jwt', 'sfdx-url', or 'access-token' (required unless skip_auth is true)"
    required: false
    default: "jwt"

  # JWT Authentication inputs
  jwt_key:
    description: "SFDX JWT Private Key (required when auth_method is 'jwt')"
    required: false

  client_id:
    description: "Connected App Client ID (required for 'jwt' and 'access-token' auth methods)"
    required: false

  username:
    description: "Salesforce Username (required when auth_method is 'jwt')"
    required: false

  # SFDX Auth URL inputs
  sfdx_auth_url:
    description: "SFDX Auth URL (required when auth_method is 'sfdx-url')"
    required: false

  # Direct Access Token inputs
  allow_access_token_auth:
    description: "Explicitly allow direct access token authentication. Advanced use only."
    required: false
    default: "true"

  access_token:
    description: "Salesforce Access Token (required when auth_method is 'access-token')"
    required: false

  alias:
    description: "Org alias for authenticated org"
    required: false
    default: "TargetOrg"

  is_dev_hub:
    description: "Set org as default Dev Hub"
    required: false
    default: "false"

  instance_url:
    description: "Salesforce instance URL (required for 'jwt' and 'access-token' methods, e.g., https://login.salesforce.com)"
    required: false
    default: "https://login.salesforce.com"

  # ============================================================================
  # OPTIONAL TOOLING
  # ============================================================================
  install_delta:
    description: "Install sfdx-git-delta for delta deployments"
    required: false
    default: "false"

  install_scanner:
    description: "Install Salesforce Code Analyzer for static analysis"
    required: false
    default: "false"

  install_prettier:
    description: "Install Prettier with Salesforce plugins for code formatting"
    required: false
    default: "false"

  install_eslint:
    description: "Install ESLint with Salesforce plugins for linting"
    required: false
    default: "false"

  install_lwc_jest:
    description: "Install @salesforce/sfdx-lwc-jest for LWC unit testing"
    required: false
    default: "false"

  custom_sf_plugins:
    description: "Comma-separated list of additional Salesforce CLI plugins to install (e.g., 'sfdx-hardis,@salesforce/plugin-packaging')"
    required: false
    default: ""

  # ============================================================================
  # SOURCE DIRECTORY RESOLUTION
  # ============================================================================
  source_dirs:
    description: "Comma-separated source directories (e.g., 'force-app,packages/core')"
    required: false
    default: "force-app"

outputs:
  org_id:
    description: "Authenticated Salesforce Org ID"
    value: ${{ steps.detect-org.outputs.org_id }}

  org_edition:
    description: "Salesforce Edition (Developer, Enterprise, Unlimited, etc.)"
    value: ${{ steps.detect-org.outputs.org_edition }}

  org_type:
    description: "Organization type (Production, Sandbox, or Scratch)"
    value: ${{ steps.detect-org.outputs.org_type }}

  username:
    description: "Authenticated username"
    value: ${{ steps.detect-org.outputs.username }}

  instance_url:
    description: "Org instance URL"
    value: ${{ steps.detect-org.outputs.instance_url }}

  api_version:
    description: "Salesforce API version for the org"
    value: ${{ steps.detect-org.outputs.api_version }}

  auth_performed:
    description: "Whether authentication was performed (true) or skipped (false)"
    value: ${{ steps.auth-status.outputs.auth_performed }}

  sf_cli_version:
    description: "Installed Salesforce CLI version"
    value: ${{ steps.install-cli.outputs.cli_version }}

  source_flags:
    description: "Resolved source directory flags for SF CLI commands"
    value: ${{ steps.resolve-source-dirs.outputs.source_flags }}

  used_default_node:
    description: "Whether the default Node.js version was used (true) or explicit version specified (false)"
    value: ${{ steps.track-defaults.outputs.used_default_node }}

  used_default_cli_version:
    description: "Whether the default CLI version was used (true) or explicit version specified (false)"
    value: ${{ steps.track-defaults.outputs.used_default_cli_version }}

  used_default_api_version:
    description: "Whether the API version was auto-detected (true) or explicitly provided (false)"
    value: ${{ steps.track-defaults.outputs.used_default_api_version }}

  cli_binary_path:
    description: "Absolute path to the sf executable (for custom tooling integration)"
    value: ${{ steps.install-cli.outputs.cli_path }}

  validated_config:
    description: "JSON summary of the final configuration (debug/audit use)"
    value: ${{ steps.track-defaults.outputs.config_json }}

runs:
  using: "composite"
  steps:
    # --------------------------------------------------------------------------
    # CORE SETUP
    # --------------------------------------------------------------------------
    - name: Setup Node.js
      uses: actions/setup-node@v4
      with:
        node-version: ${{ inputs.node_version }}

    - name: Detect Operating System
      id: detect-os
      shell: bash
      run: |
        set -euo pipefail

        echo "🔍 Detecting operating system..."

        case "${{ runner.os }}" in
          Linux)
            echo "os_type=linux" >> $GITHUB_OUTPUT
            echo "package_manager=apt" >> $GITHUB_OUTPUT
            echo "  ✅ OS: Linux (apt package manager)"
            ;;
          macOS)
            echo "os_type=macos" >> $GITHUB_OUTPUT
            echo "package_manager=brew" >> $GITHUB_OUTPUT
            echo "  ✅ OS: macOS (brew package manager)"
            ;;
          Windows)
            echo "os_type=windows" >> $GITHUB_OUTPUT
            echo "package_manager=choco" >> $GITHUB_OUTPUT
            echo "  ✅ OS: Windows (choco package manager)"
            ;;
          *)
            echo "os_type=unknown" >> $GITHUB_OUTPUT
            echo "package_manager=none" >> $GITHUB_OUTPUT
            echo "  ⚠️  OS: Unknown"
            ;;
        esac

    - name: Ensure dependencies (jq) - Linux
      if: steps.detect-os.outputs.os_type == 'linux'
      shell: bash
      run: |
        set -euo pipefail

        if ! command -v jq &> /dev/null; then
          echo "📦 Installing jq on Linux..."
          sudo apt-get update && sudo apt-get install -y jq
          echo "  ✅ jq installed successfully"
        else
          echo "✅ jq already installed"
        fi

    - name: Ensure dependencies (jq) - macOS
      if: steps.detect-os.outputs.os_type == 'macos'
      shell: bash
      run: |
        set -euo pipefail

        if ! command -v jq &> /dev/null; then
          echo "📦 Installing jq on macOS..."
          brew install jq
          echo "  ✅ jq installed successfully"
        else
          echo "✅ jq already installed"
        fi

    - name: Ensure dependencies (jq) - Windows
      if: steps.detect-os.outputs.os_type == 'windows'
      shell: pwsh
      run: |
        if (!(Get-Command jq -ErrorAction SilentlyContinue)) {
          Write-Host "📦 Installing jq on Windows..."
          choco install jq -y
          Write-Host "  ✅ jq installed successfully"
        } else {
          Write-Host "✅ jq already installed"
        }

    - name: Generate cache key
      id: cache-key
      shell: bash
      run: |
        set -euo pipefail

        echo "🔑 Generating cache key..."

        # Tooling hash
        if command -v sha256sum >/dev/null 2>&1; then
          HASH_CMD="sha256sum"
        elif command -v shasum >/dev/null 2>&1; then
          HASH_CMD="shasum -a 256"
        else
          HASH_CMD="echo"
        fi

        TOOLS_HASH=$(echo "${{ inputs.install_delta }}-${{ inputs.install_scanner }}-${{ inputs.install_prettier }}-${{ inputs.install_eslint }}-${{ inputs.install_lwc_jest }}-${{ inputs.custom_sf_plugins }}" \
              | $HASH_CMD | awk '{print $1}' | cut -c1-8)


        echo "tools_hash=$TOOLS_HASH" >> $GITHUB_OUTPUT

        CLI_VERSION_INPUT="${{ inputs.cli_version }}"
        CLI_CACHE_VERSION=""

        if [ "$CLI_VERSION_INPUT" = "latest" ]; then
          echo "📦 Resolving actual Salesforce CLI version for cache..."

          # OPTIMIZATION: Fetch version from npm instead of installing
          # This prevents a full install just to check the version number
          # Check for timeout command (gnu coreutils)
          if command -v timeout >/dev/null 2>&1; then
            ACTUAL_VERSION=$(timeout 10 npm view @salesforce/cli version 2>/dev/null || true)
          else
            ACTUAL_VERSION=$(npm view @salesforce/cli version 2>/dev/null || true)
          fi

          if [ -z "$ACTUAL_VERSION" ]; then
            # Use monthly rotation for cache when npm is unreachable
            ACTUAL_VERSION="latest-$(date +%Y-%m)"
            echo "⚠️ Could not resolve version from npm. Using time-based cache: $ACTUAL_VERSION"
            echo "💡 Cache will rotate monthly to ensure freshness"
          fi

          echo "  Detected CLI version: $ACTUAL_VERSION"

          case "${{ inputs.cli_version_for_cache }}" in
            major)
              CLI_CACHE_VERSION=$(echo "$ACTUAL_VERSION" | cut -d. -f1)
              ;;
            minor)
              CLI_CACHE_VERSION=$(echo "$ACTUAL_VERSION" | cut -d. -f1-2)
              ;;
            exact)
              CLI_CACHE_VERSION="$ACTUAL_VERSION"
              ;;
            *)
              CLI_CACHE_VERSION=$(echo "$ACTUAL_VERSION" | cut -d. -f1-2)
              ;;
          esac
        else
          case "${{ inputs.cli_version_for_cache }}" in
            major)
              CLI_CACHE_VERSION=$(echo "$CLI_VERSION_INPUT" | cut -d. -f1)
              ;;
            minor)
              CLI_CACHE_VERSION=$(echo "$CLI_VERSION_INPUT" | cut -d. -f1-2)
              ;;
            exact)
              CLI_CACHE_VERSION="$CLI_VERSION_INPUT"
              ;;
            *)
              CLI_CACHE_VERSION=$(echo "$CLI_VERSION_INPUT" | cut -d. -f1-2)
              ;;
          esac
        fi

        echo "cli_cache_version=$CLI_CACHE_VERSION" >> $GITHUB_OUTPUT
        echo "  ✅ Cache key uses CLI version: $CLI_CACHE_VERSION"
        echo "  ✅ Tools hash: $TOOLS_HASH"

    - name: Cache Salesforce CLI and plugins (Unix)
      if: runner.os != 'Windows'
      uses: actions/cache@v4
      with:
        path: |
          ~/.npm
          ~/.local/share/sf
          ~/.cache/node-gyp
        key: sf-v3-${{ runner.os }}-node${{ inputs.node_version }}-cli${{ steps.cache-key.outputs.cli_cache_version }}-tools${{ steps.cache-key.outputs.tools_hash }}
        restore-keys: |
          sf-v3-${{ runner.os }}-node${{ inputs.node_version }}-cli${{ steps.cache-key.outputs.cli_cache_version }}-
          sf-v3-${{ runner.os }}-node${{ inputs.node_version }}-

    - name: Cache Salesforce CLI and plugins (Windows)
      if: runner.os == 'Windows'
      uses: actions/cache@v4
      with:
        path: |
          ~/AppData/Local/sf
          ~/AppData/Roaming/npm
        key: sf-v3-${{ runner.os }}-node${{ inputs.node_version }}-cli${{ steps.cache-key.outputs.cli_cache_version }}-tools${{ steps.cache-key.outputs.tools_hash }}
        restore-keys: |
          sf-v3-${{ runner.os }}-node${{ inputs.node_version }}-cli${{ steps.cache-key.outputs.cli_cache_version }}-
          sf-v3-${{ runner.os }}-node${{ inputs.node_version }}-

    - name: Install Salesforce CLI
      id: install-cli
      shell: bash
      run: |
        set -euo pipefail

        if ! command -v sf &> /dev/null; then
          echo "📦 Installing Salesforce CLI..."
          
          MAX_RETRIES=3
          RETRY_COUNT=0
          BASE_DELAY=5
          
          while [ $RETRY_COUNT -lt $MAX_RETRIES ]; do
            # Calculate exponential backoff: 5s, 10s, 20s
            DELAY=$((BASE_DELAY * (2 ** RETRY_COUNT)))
            
            echo "  Attempt $((RETRY_COUNT + 1)) of $MAX_RETRIES..."
            
            if [ "${{ inputs.cli_version }}" = "latest" ]; then
              INSTALL_CMD="npm install -g @salesforce/cli"
            else
              INSTALL_CMD="npm install -g @salesforce/cli@${{ inputs.cli_version }}"
            fi
            
            if $INSTALL_CMD; then
              echo "  ✅ Salesforce CLI installed successfully"
              break
            fi
            
            RETRY_COUNT=$((RETRY_COUNT + 1))
            
            if [ $RETRY_COUNT -lt $MAX_RETRIES ]; then
              echo "  ⚠️  Installation failed, waiting ${DELAY}s before retry..."
              sleep $DELAY
            else
              echo "❌ Failed to install Salesforce CLI after $MAX_RETRIES attempts"
              echo "💡 This may be due to:"
              echo "   - Network connectivity issues"
              echo "   - npm registry availability"
              echo "   - GitHub Actions rate limiting"
              echo "   - Retry the workflow or use a specific CLI version"
              exit 1
            fi
          done
        else
          echo "✅ Salesforce CLI already installed"
        fi

        CLI_VERSION=$(sf --version | head -n 1)
        echo "📊 Installed: $CLI_VERSION"
        echo "cli_version=$CLI_VERSION" >> $GITHUB_OUTPUT

        # Capture and output CLI binary path (Forward Compatibility for v4)
        CLI_PATH=$(command -v sf)
        echo "cli_path=$CLI_PATH" >> $GITHUB_OUTPUT
        echo "📍 CLI Binary: $CLI_PATH"

        # Inline Health Check
        if ! sf plugins --core >/dev/null 2>&1; then
          echo "❌ CLI installed but not responding correctly"
          exit 1
        fi
        echo "✅ CLI verified and functional"

    # --------------------------------------------------------------------------
    # SOURCE DIRECTORY RESOLUTION
    # --------------------------------------------------------------------------
    - name: Resolve Source Directories
      id: resolve-source-dirs
      shell: bash
      run: |
        set -euo pipefail

        RAW_INPUT="${{ inputs.source_dirs }}"
        [ -z "$RAW_INPUT" ] && RAW_INPUT="force-app"

        IFS=',' read -ra DIRS <<< "$RAW_INPUT"
        FLAGS=""
        HAS_VALID_DIR=false

        echo "📁 Resolving source directories..."

        for dir in "${DIRS[@]}"; do
          dir=$(echo "$dir" | xargs)
          
          if [ -d "$dir" ]; then
            FLAGS="$FLAGS --source-dir $dir"
            HAS_VALID_DIR=true
            echo "  ✅ Found: $dir"
          elif [ "$dir" == "force-app" ]; then
            echo "  ⚠️  Default directory '$dir' not found. Creating it..."
            mkdir -p "$dir"
            FLAGS="$FLAGS --source-dir $dir"
            HAS_VALID_DIR=true
            echo "  ✅ Created: $dir"
          else
            echo "  ⚠️  Warning: Directory '$dir' not found"
          fi
        done

        if [ "$HAS_VALID_DIR" = "false" ]; then
          echo "❌ Error: No valid source directories found."
          echo ""
          echo "💡 Tips:"
          echo "   • Default 'force-app' is auto-created if missing"
          echo "   • Custom directories must exist in your repository"
          echo "   • Check your source_dirs input for typos"
          exit 1
        fi

        echo "source_flags=$FLAGS" >> $GITHUB_OUTPUT
        echo "✅ Source directories resolved"

    # --------------------------------------------------------------------------
    # INPUT VALIDATION
    # --------------------------------------------------------------------------
    - name: Validate authentication inputs
      if: inputs.skip_auth != 'true' && inputs.dry_run != 'true'
      shell: bash
      run: |
        set -euo pipefail

        echo "🔐 Validating authentication inputs..."
        echo "  Auth method: ${{ inputs.auth_method }}"

        MISSING_INPUTS=()

        case "${{ inputs.auth_method }}" in
          jwt)
            echo "  Using JWT authentication"
            
            [ -z "${{ inputs.jwt_key }}" ] && MISSING_INPUTS+=("jwt_key")
            [ -z "${{ inputs.client_id }}" ] && MISSING_INPUTS+=("client_id")
            [ -z "${{ inputs.username }}" ] && MISSING_INPUTS+=("username")
            ;;
            
          sfdx-url)
            echo "  Using SFDX Auth URL authentication"
            
            [ -z "${{ inputs.sfdx_auth_url }}" ] && MISSING_INPUTS+=("sfdx_auth_url")
            ;;
            
          access-token)

            echo "  Using Direct Access Token authentication"

            if [ "${{ inputs.auth_method }}" = "access-token" ] && [ "${{ inputs.allow_access_token_auth }}" != "true" ]; then
              echo "❌ Error: access-token authentication is disabled by default"
              echo "   Set allow_access_token_auth: true to explicitly enable it"
              exit 1
            fi
            
            [ -z "${{ inputs.access_token }}" ] && MISSING_INPUTS+=("access_token")
            [ -z "${{ inputs.instance_url }}" ] && MISSING_INPUTS+=("instance_url")
            ;;
            
          *)
            echo "❌ Error: Invalid auth_method '${{ inputs.auth_method }}'"
            echo "   Must be one of: jwt, sfdx-url, access-token"
            exit 1
            ;;
        esac

        if [ ${#MISSING_INPUTS[@]} -gt 0 ]; then
          echo "❌ Error: The following required inputs are missing for ${{ inputs.auth_method }} authentication:"
          printf '  - %s\\n' "${MISSING_INPUTS[@]}"
          exit 1
        fi

        echo "✅ Authentication inputs validated"

    # --------------------------------------------------------------------------
    # AUTHENTICATION
    # --------------------------------------------------------------------------
    - name: Authenticate Org (JWT)
      if: inputs.skip_auth != 'true' && inputs.dry_run != 'true' && inputs.auth_method == 'jwt'
      shell: bash
      env:
        JWT_KEY: ${{ inputs.jwt_key }}
      run: |
        set -euo pipefail

        echo "🔐 Authenticating via JWT..."
        echo "  Client ID: ${{ inputs.client_id && '***' || '(not set)' }}"
        echo "  Username: ${{ inputs.username }}"
        echo "  Instance URL: ${{ inputs.instance_url }}"
        echo "  Alias: ${{ inputs.alias }}"

        # Create JWT key file with secure permissions using env var
        echo "$JWT_KEY" > jwt.key

        # Set secure permissions
        # Set secure permissions (Critical for Unix)
        if [[ "${{ runner.os }}" != "Windows" ]]; then
          chmod 600 jwt.key
        fi

        # Cleanup function
        cleanup() {
          echo "  🧹 Cleaning up JWT key file..."
          rm -f jwt.key
        }
        trap cleanup EXIT

        # Add dev hub or default flag
        if [ "${{ inputs.is_dev_hub }}" = "true" ]; then
          echo "  🔧 Setting as Dev Hub..."
          sf org login jwt \
            --client-id "${{ inputs.client_id }}" \
            --jwt-key-file jwt.key \
            --username "${{ inputs.username }}" \
            --instance-url "${{ inputs.instance_url }}" \
            --alias "${{ inputs.alias }}" \
            --set-default-dev-hub
        else
          echo "  🔧 Setting as default org..."
          sf org login jwt \
            --client-id "${{ inputs.client_id }}" \
            --jwt-key-file jwt.key \
            --username "${{ inputs.username }}" \
            --instance-url "${{ inputs.instance_url }}" \
            --alias "${{ inputs.alias }}" \
            --set-default
        fi

        echo "✅ JWT authentication successful"

    - name: Authenticate Org (SFDX Auth URL)
      if: inputs.skip_auth != 'true' && inputs.dry_run != 'true' && inputs.auth_method == 'sfdx-url'
      shell: bash
      env:
        SFDX_AUTH_URL: ${{ inputs.sfdx_auth_url }}
      run: |
        set -euo pipefail

        echo "🔐 Authenticating via SFDX Auth URL..."
        echo "  Alias: ${{ inputs.alias }}"

        # Create auth URL file with secure permissions using env var
        echo "$SFDX_AUTH_URL" > authurl.txt

        # Set secure permissions
        if [[ "${{ runner.os }}" != "Windows" ]]; then
          chmod 600 authurl.txt
        fi

        # Cleanup function
        cleanup() {
          echo "  🧹 Cleaning up auth URL file..."
          rm -f authurl.txt
        }
        trap cleanup EXIT

        # Authenticate using SFDX auth URL
        AUTH_CMD="sf org login sfdx-url \
          --sfdx-url-file authurl.txt \
          --alias ${{ inputs.alias }}"

        # Add dev hub or default flag
        if [ "${{ inputs.is_dev_hub }}" = "true" ]; then
          echo "  🔧 Setting as Dev Hub..."
          $AUTH_CMD --set-default-dev-hub
        else
          echo "  🔧 Setting as default org..."
          $AUTH_CMD --set-default
        fi

        echo "✅ SFDX Auth URL authentication successful"

    - name: Authenticate Org (Access Token)
      if: inputs.skip_auth != 'true' && inputs.dry_run != 'true' && inputs.auth_method == 'access-token'
      shell: bash
      env:
        SF_ACCESS_TOKEN: ${{ inputs.access_token }}
      run: |
        set -euo pipefail

        echo "🔐 Authenticating via Direct Access Token..."
        echo "  ⚠️ WARNING: Access tokens are short-lived and recommended for advanced use only"
        echo "  ⚠️ For production workflows, use JWT or SFDX Auth URL authentication"
        echo "  Instance URL: ${{ inputs.instance_url }}"
        echo "  Alias: ${{ inputs.alias }}"

        # Use SF_ACCESS_TOKEN environment variable (per Salesforce CLI documentation)
        # The --no-prompt flag reads from SF_ACCESS_TOKEN env var
        sf org login access-token \
          --instance-url "${{ inputs.instance_url }}" \
          --alias ${{ inputs.alias }} \
          --no-prompt

        # Add dev hub or default flag
        if [ "${{ inputs.is_dev_hub }}" = "true" ]; then
          echo "  🔧 Setting as Dev Hub..."
          sf config set target-dev-hub=${{ inputs.alias }} --global
        else
          echo "  🔧 Setting as default org..."
          sf config set target-org=${{ inputs.alias }} --global
        fi

        echo "✅ Access Token authentication successful"

    - name: Detect Org Details
      id: detect-org
      if: inputs.skip_auth != 'true' && inputs.dry_run != 'true'
      shell: bash
      run: |
        set -euo pipefail

        echo "🔍 Retrieving org details..."
        DETAILS=$(sf org display --target-org ${{ inputs.alias }} --json)

        # Extract org information with better fallbacks
        ORG_ID=$(echo "$DETAILS" | jq -r '.result.id // .result.orgId // "unknown"')
        ORG_EDITION=$(echo "$DETAILS" | jq -r '.result.edition // "unknown"')
        USERNAME=$(echo "$DETAILS" | jq -r '.result.username // "unknown"')
        INSTANCE_URL=$(echo "$DETAILS" | jq -r '.result.instanceUrl // "unknown"')
        API_VERSION=$(echo "$DETAILS" | jq -r '.result.apiVersion // "unknown"')

        # Try multiple fields for sandbox detection
        IS_SANDBOX=$(echo "$DETAILS" | jq -r '.result.isSandbox // false | tostring')
        IS_SCRATCH=$(echo "$DETAILS" | jq -r '.result.isScratchOrg // false | tostring')

        # Additional check: sandbox orgs often have instanceUrl containing "cs" or "sandbox"
        if [ "$IS_SANDBOX" = "false" ] && [[ "$INSTANCE_URL" =~ (cs[0-9]+|sandbox) ]]; then
          echo "  ℹ️  Detected sandbox from instance URL pattern"
          IS_SANDBOX="true"
        fi

        # Check org namespace/status which can indicate sandbox
        ORG_STATUS=$(echo "$DETAILS" | jq -r '.result.status // "unknown"')
        ORG_TYPE_RAW=$(echo "$DETAILS" | jq -r '.result.organizationType // "unknown"')

        # Determine org type with improved logic
        if [ "$IS_SCRATCH" = "true" ]; then
          ORG_TYPE="Scratch"
        elif [ "$IS_SANDBOX" = "true" ]; then
          ORG_TYPE="Sandbox"
        elif [[ "$ORG_TYPE_RAW" =~ [Ss]andbox ]]; then
          ORG_TYPE="Sandbox"
        elif [[ "$ORG_EDITION" =~ Developer ]]; then
          # Developer editions are typically production but worth noting
          ORG_TYPE="Production"
        else
          ORG_TYPE="Production"
        fi

        # Set outputs
        echo "org_id=$ORG_ID" >> $GITHUB_OUTPUT
        echo "org_edition=$ORG_EDITION" >> $GITHUB_OUTPUT
        echo "org_type=$ORG_TYPE" >> $GITHUB_OUTPUT
        echo "username=$USERNAME" >> $GITHUB_OUTPUT
        echo "instance_url=$INSTANCE_URL" >> $GITHUB_OUTPUT
        echo "api_version=$API_VERSION" >> $GITHUB_OUTPUT

        # Display summary
        echo ""
        echo "📊 Org Details Summary:"
        echo "  ├─ Type: $ORG_TYPE"
        echo "  ├─ Edition: $ORG_EDITION"
        echo "  ├─ Org ID: $ORG_ID"
        echo "  ├─ Username: $USERNAME"
        echo "  ├─ Instance: $INSTANCE_URL"
        echo "  └─ API Version: $API_VERSION"
        echo ""

        if [ "$ORG_TYPE" = "Production" ] && [[ "$INSTANCE_URL" =~ (cs[0-9]+|sandbox) ]]; then
          echo "⚠️  WARNING: Org type detected as Production but instance URL suggests Sandbox"
          echo "   If this is incorrect, please report this issue with your org details"
        fi

    - name: Set Authentication Status
      id: auth-status
      shell: bash
      run: |
        set -euo pipefail

        if [ "${{ inputs.skip_auth }}" = "true" ] || [ "${{ inputs.dry_run }}" = "true" ]; then
          echo "auth_performed=false" >> $GITHUB_OUTPUT
          if [ "${{ inputs.dry_run }}" = "true" ]; then
            echo "ℹ️  Authentication skipped (dry-run mode)"
          else
            echo "ℹ️  Authentication skipped"
          fi
        else
          echo "auth_performed=true" >> $GITHUB_OUTPUT
          echo "✅ Authentication completed"
        fi

    - name: Track Default Usage
      id: track-defaults
      shell: bash
      run: |
        set -euo pipefail

        echo "📊 Tracking default usage..."

        # Track Node.js version default
        if [ "${{ inputs.node_version }}" = "20" ]; then
          echo "used_default_node=true" >> $GITHUB_OUTPUT
          echo "  ⚠️  Using default Node.js version: 20"
        else
          echo "used_default_node=false" >> $GITHUB_OUTPUT
          echo "  ✅ Using explicit Node.js version: ${{ inputs.node_version }}"
        fi

        # Track CLI version default
        if [ "${{ inputs.cli_version }}" = "latest" ]; then
          echo "used_default_cli_version=true" >> $GITHUB_OUTPUT
          echo "  ⚠️  Using default CLI version: latest"
        else
          echo "used_default_cli_version=false" >> $GITHUB_OUTPUT
          echo "  ✅ Using explicit CLI version: ${{ inputs.cli_version }}"
        fi

        # API version is always auto-detected in current implementation
        # API version is always auto-detected in current implementation
        echo "used_default_api_version=true" >> $GITHUB_OUTPUT
        echo "  ℹ️  API version auto-detected from org"

        # Generate JSON Configuration Summary (Forward Compatibility for v4)
        # This provides a structured audit record of the final configuration
        CONFIG_JSON="{\"node_version\":\"${{ inputs.node_version }}\",\"cli_version\":\"${{ inputs.cli_version }}\",\"auth_method\":\"${{ inputs.auth_method }}\",\"skip_auth\":${{ inputs.skip_auth }},\"dry_run\":${{ inputs.dry_run }}}"
        echo "config_json=$CONFIG_JSON" >> $GITHUB_OUTPUT

    # --------------------------------------------------------------------------
    # OPTIONAL TOOLING (with strict mode awareness)
    # --------------------------------------------------------------------------
    - name: Install sfdx-git-delta
      if: inputs.install_delta == 'true'
      shell: bash
      run: |
        set -eu  # Always fail on undefined variables
        if [ "${{ inputs.strict }}" = "true" ]; then
          set -o pipefail
        fi

        if ! sf plugins inspect sfdx-git-delta >/dev/null 2>&1; then
          echo "📦 Installing sfdx-git-delta..."
          
          MAX_RETRIES=3
          RETRY_COUNT=0
          BASE_DELAY=5
          
          while [ $RETRY_COUNT -lt $MAX_RETRIES ]; do
            DELAY=$((BASE_DELAY * (2 ** RETRY_COUNT)))
            echo "  Attempt $((RETRY_COUNT + 1)) of $MAX_RETRIES..."
            
            if echo y | sf plugins install sfdx-git-delta 2>&1; then
              echo "  ✅ sfdx-git-delta installed"
              break
            fi
            
            RETRY_COUNT=$((RETRY_COUNT + 1))
            
            if [ $RETRY_COUNT -lt $MAX_RETRIES ]; then
              echo "  ⚠️  Installation failed, waiting ${DELAY}s before retry..."
              sleep $DELAY
            else
              echo "  ❌ Failed to install sfdx-git-delta after $MAX_RETRIES attempts"
              if [ "${{ inputs.strict }}" = "true" ]; then
                exit 1
              fi
            fi
          done
        else
          echo "✅ sfdx-git-delta already installed"
        fi

    - name: Install Salesforce Code Analyzer
      if: inputs.install_scanner == 'true'
      shell: bash
      run: |
        set -eu  # Always fail on undefined variables
        if [ "${{ inputs.strict }}" = "true" ]; then
          set -o pipefail
        fi

        if ! sf plugins inspect @salesforce/plugin-code-analyzer >/dev/null 2>&1; then
          echo "📦 Installing @salesforce/plugin-code-analyzer..."
          
          MAX_RETRIES=3
          RETRY_COUNT=0
          BASE_DELAY=5
          
          while [ $RETRY_COUNT -lt $MAX_RETRIES ]; do
            DELAY=$((BASE_DELAY * (2 ** RETRY_COUNT)))
            echo "  Attempt $((RETRY_COUNT + 1)) of $MAX_RETRIES..."
            
            if echo y | sf plugins install @salesforce/plugin-code-analyzer 2>&1; then
              echo "  ✅ Code Analyzer installed"
              break
            fi
            
            RETRY_COUNT=$((RETRY_COUNT + 1))
            
            if [ $RETRY_COUNT -lt $MAX_RETRIES ]; then
              echo "  ⚠️  Installation failed, waiting ${DELAY}s before retry..."
              sleep $DELAY
            else
              echo "  ❌ Failed to install Code Analyzer after $MAX_RETRIES attempts"
              if [ "${{ inputs.strict }}" = "true" ]; then
                exit 1
              fi
            fi
          done
        else
          echo "✅ Code Analyzer already installed"
        fi

    - name: Install Custom Salesforce CLI Plugins
      if: inputs.custom_sf_plugins != ''
      shell: bash
      run: |
        set -eu  # Always fail on undefined variables
        if [ "${{ inputs.strict }}" = "true" ]; then
          set -o pipefail
        fi

        echo "📦 Installing custom Salesforce CLI plugins..."

        IFS=',' read -ra PLUGIN_LIST <<< "${{ inputs.custom_sf_plugins }}"
        FAILED_PLUGINS=()
        INSTALLED_PLUGINS=()
        SKIPPED_PLUGINS=()

        for plugin in "${PLUGIN_LIST[@]}"; do
          # Trim whitespace
          plugin=$(echo "$plugin" | xargs)
              
          # Skip empty entries
          if [ -z "$plugin" ]; then
            continue
          fi
              
          # Validate plugin name format
          # Accepts: @scope/plugin-name OR plugin-name
          # Rejects: @scope/, @scope, @@invalid, @/name, etc.
          # Supports dots in package names (e.g. my.plugin)
          if ! echo "$plugin" | grep -qE '^(@[a-zA-Z0-9._-]+/[a-zA-Z0-9._-]+|[a-zA-Z0-9@._-]+)$'; then
            echo "  ⚠️  Invalid plugin name format: '$plugin'"
            echo "     Valid formats:"
            echo "       - Scoped: @scope/plugin-name"
            echo "       - Unscoped: plugin-name"
            echo "     Must contain only: letters, numbers, hyphens, underscores"
            FAILED_PLUGINS+=("$plugin (invalid format)")
            if [ "${{ inputs.strict }}" = "true" ]; then
              exit 1
            fi
            continue
          fi
              
          # Check if already installed
          if sf plugins inspect "$plugin" >/dev/null 2>&1; then
            echo "  ✅ $plugin already installed"
            SKIPPED_PLUGINS+=("$plugin")
            continue
          fi
              
          # Install the plugin with retry logic
          echo "  📦 Installing: $plugin"
          
          PLUGIN_RETRIES=3
          PLUGIN_ATTEMPT=0
          PLUGIN_DELAY=5
          INSTALL_SUCCESS=false
          
          while [ $PLUGIN_ATTEMPT -lt $PLUGIN_RETRIES ]; do
            CURRENT_DELAY=$((PLUGIN_DELAY * (2 ** PLUGIN_ATTEMPT)))
            
            if echo y | sf plugins install "$plugin" 2>&1; then
              echo "    ✅ Installed successfully"
              INSTALLED_PLUGINS+=("$plugin")
              INSTALL_SUCCESS=true
              break
            fi
            
            PLUGIN_ATTEMPT=$((PLUGIN_ATTEMPT + 1))
            
            if [ $PLUGIN_ATTEMPT -lt $PLUGIN_RETRIES ]; then
              echo "    ⚠️  Attempt $PLUGIN_ATTEMPT failed, retrying in ${CURRENT_DELAY}s..."
              sleep $CURRENT_DELAY
            fi
          done
          
          if [ "$INSTALL_SUCCESS" = "false" ]; then
            echo "    ❌ Failed to install after $PLUGIN_RETRIES attempts"
            FAILED_PLUGINS+=("$plugin")
            if [ "${{ inputs.strict }}" = "true" ]; then
              exit 1
            fi
          fi
        done

        # Summary
        echo ""
        echo "📊 Plugin Installation Summary:"
        echo "   ├─ Installed: ${#INSTALLED_PLUGINS[@]}"
        echo "   ├─ Already Present: ${#SKIPPED_PLUGINS[@]}"
        echo "   └─ Failed: ${#FAILED_PLUGINS[@]}"

        if [ ${#FAILED_PLUGINS[@]} -gt 0 ]; then
          echo ""
          echo "⚠️  Failed Plugins:"
          printf '   - %s\n' "${FAILED_PLUGINS[@]}"
          
          if [ "${{ inputs.strict }}" = "true" ]; then
            echo ""
            echo "❌ Strict mode enabled: Failing workflow due to plugin errors"
            exit 1
          else
            echo ""
            echo "💡 Non-strict mode: Continuing despite failures"
            echo "   Set strict: 'true' to fail on plugin errors"
          fi
        fi

    - name: Install Prettier and plugins
      if: inputs.install_prettier == 'true'
      shell: bash
      run: |
        set -eu  # Always fail on undefined variables
        if [ "${{ inputs.strict }}" = "true" ]; then
          set -o pipefail
        fi

        if ! command -v prettier &> /dev/null; then
          echo "📦 Installing Prettier with Salesforce plugins..."
          npm install --global prettier prettier-plugin-apex @prettier/plugin-xml
          echo "  ✅ Prettier installed"
        else
          echo "✅ Prettier already installed"
        fi

    - name: Install ESLint and plugins
      if: inputs.install_eslint == 'true'
      shell: bash
      run: |
        set -eu  # Always fail on undefined variables
        if [ "${{ inputs.strict }}" = "true" ]; then
          set -o pipefail
        fi

        if ! command -v eslint &> /dev/null; then
          echo "📦 Installing ESLint with Salesforce plugins..."
          npm install --global eslint @salesforce/eslint-config-lwc @lwc/eslint-plugin-lwc
          echo "  ✅ ESLint installed"
        else
          echo "✅ ESLint already installed"
        fi

    - name: Install sfdx-lwc-jest
      if: inputs.install_lwc_jest == 'true'
      shell: bash
      run: |
        set -eu  # Always fail on undefined variables
        if [ "${{ inputs.strict }}" = "true" ]; then
          set -o pipefail
        fi

        if ! npm list -g @salesforce/sfdx-lwc-jest &> /dev/null; then
          echo "📦 Installing @salesforce/sfdx-lwc-jest..."
          # NOTE: This installs the latest version globally.
          # If your project has a specific version in package.json,
          # you may want to run 'npm install' locally instead to
          # avoid version mismatches with your LWC API version.
          npm install --global @salesforce/sfdx-lwc-jest
          echo "  ✅ sfdx-lwc-jest installed"
        else
          echo "✅ sfdx-lwc-jest already installed"
        fi

    # --------------------------------------------------------------------------
    # INVARIANT VALIDATION
    # --------------------------------------------------------------------------
    - name: Validate Setup Invariants
      shell: bash
      run: |
        set -euo pipefail

        echo "🔒 Validating setup invariants..."

        # 1. CLI is callable and functional
        if ! sf version --json >/dev/null 2>&1; then
          echo "❌ INVARIANT VIOLATION: CLI not functional"
          echo "   The Salesforce CLI was installed but is not responding correctly"
          exit 1
        fi
        echo "  ✅ CLI functional"

        # 2. Org is reachable (only if auth was performed)
        if [ "${{ inputs.skip_auth }}" != "true" ] && [ "${{ inputs.dry_run }}" != "true" ]; then
          if ! sf org display --target-org "${{ inputs.alias }}" --json >/dev/null 2>&1; then
            echo "❌ INVARIANT VIOLATION: Org not reachable"
            echo "   Authentication appeared to succeed but org is not accessible"
            exit 1
          fi
          echo "  ✅ Org reachable"
          
          # 3. API version resolved
          API_VERSION="${{ steps.detect-org.outputs.api_version }}"
          if [ -z "$API_VERSION" ] || [ "$API_VERSION" = "unknown" ]; then
            echo "❌ INVARIANT VIOLATION: API version not resolved"
            echo "   Org is reachable but API version could not be determined"
            exit 1
          fi
          echo "  ✅ API version resolved ($API_VERSION)"
        else
          echo "  ⏭️  Skipping org validation (auth skipped or dry-run mode)"
        fi

        echo ""
        echo "✅ All invariants validated - setup is guaranteed functional"

    # --------------------------------------------------------------------------
    # FINAL STATUS
    # --------------------------------------------------------------------------
    - name: Environment Ready
      shell: bash
      run: |
        set -euo pipefail

        echo ""
        echo "🎉 Salesforce environment is ready!"
        echo ""
        echo "📊 Installed Tools:"
        echo "  ├─ Salesforce CLI: $(sf --version | head -n 1)"
        [ "${{ inputs.install_delta }}" = "true" ] && echo "  ├─ sfdx-git-delta: ✅" || true
        [ "${{ inputs.install_scanner }}" = "true" ] && echo "  ├─ Code Analyzer: ✅" || true
        [ "${{ inputs.install_prettier }}" = "true" ] && echo "  ├─ Prettier: ✅" || true
        [ "${{ inputs.install_eslint }}" = "true" ] && echo "  ├─ ESLint: ✅" || true
        [ "${{ inputs.install_lwc_jest }}" = "true" ] && echo "  └─ LWC Jest: ✅" || true

        if [ -n "${{ inputs.custom_sf_plugins }}" ]; then
          echo ""
          echo "🔌 Custom Plugins:"
          IFS=',' read -ra PLUGIN_LIST <<< "${{ inputs.custom_sf_plugins }}"
          PLUGIN_COUNT=${#PLUGIN_LIST[@]}
          INDEX=0
          for plugin in "${PLUGIN_LIST[@]}"; do
            plugin=$(echo "$plugin" | xargs)
            INDEX=$((INDEX + 1))
            if [ -n "$plugin" ]; then
              if [ $INDEX -eq $PLUGIN_COUNT ]; then
                echo "  └─ $plugin"
              else
                echo "  ├─ $plugin"
              fi
            fi
          done
        fi

        echo ""
        echo "✅ Setup complete - ready for Salesforce operations!"

    - name: Publish Setup Summary
      if: always()
      shell: bash
      run: |
        set -euo pipefail

        # Build summary for GitHub Actions UI
        {
          echo "## 🎯 Salesforce Environment Setup"
          echo ""
          echo "| Component | Value |"
          echo "|-----------|-------|"
          
          # Auth method and status
          if [ "${{ inputs.skip_auth }}" = "true" ] || [ "${{ inputs.dry_run }}" = "true" ]; then
            echo "| **Auth Method** | Skipped |"
          else
            echo "| **Auth Method** | \`${{ inputs.auth_method }}\` |"
            echo "| **Org Type** | ${{ steps.detect-org.outputs.org_type }} |"
            echo "| **Org Edition** | ${{ steps.detect-org.outputs.org_edition }} |"
            echo "| **API Version** | \`${{ steps.detect-org.outputs.api_version }}\` |"
            echo "| **Instance URL** | ${{ steps.detect-org.outputs.instance_url }} |"
          fi
          
          # Runtime versions
          echo "| **CLI Version** | \`${{ steps.install-cli.outputs.cli_version }}\` |"
          echo "| **Node Version** | \`${{ inputs.node_version }}\` |"
          
          # Default usage tracking
          echo ""
          echo "### ⚙️ Configuration"
          echo ""
          if [ "${{ steps.track-defaults.outputs.used_default_node }}" = "true" ]; then
            echo "- ⚠️ Using default Node.js version"
          else
            echo "- ✅ Using explicit Node.js version"
          fi
          
          if [ "${{ steps.track-defaults.outputs.used_default_cli_version }}" = "true" ]; then
            echo "- ⚠️ Using default CLI version (latest)"
          else
            echo "- ✅ Using explicit CLI version"
          fi
          
          # Installed tools
          echo ""
          echo "### 🔧 Installed Tools"
          echo ""
          echo "- Salesforce CLI"
          
          [ "${{ inputs.install_delta }}" = "true" ] && echo "- sfdx-git-delta"
          [ "${{ inputs.install_scanner }}" = "true" ] && echo "- Salesforce Code Analyzer"
          [ "${{ inputs.install_prettier }}" = "true" ] && echo "- Prettier (with Apex plugin)"
          [ "${{ inputs.install_eslint }}" = "true" ] && echo "- ESLint (with LWC plugin)"
          [ "${{ inputs.install_lwc_jest }}" = "true" ] && echo "- sfdx-lwc-jest"
          
          if [ -n "${{ inputs.custom_sf_plugins }}" ]; then
            echo ""
            echo "### 🔌 Custom Plugins"
            echo ""
            IFS=',' read -ra PLUGIN_LIST <<< "${{ inputs.custom_sf_plugins }}"
            for plugin in "${PLUGIN_LIST[@]}"; do
              plugin=$(echo "$plugin" | xargs)
              [ -n "$plugin" ] && echo "- \`$plugin\`"
            done
          fi
          
        } >> $GITHUB_STEP_SUMMARY