Job Parameters

pipeline {
    agent { label 'linux' }

    // Define all parameters here — Jenkins renders these as a form
    // when the user clicks 'Build With Parameters'
    parameters {

        // Dropdown — restricts the user to valid environments only
        choice(
            name: 'DEPLOY_ENV',
            choices: ['staging', 'qa', 'production'],
            description: 'Target environment for this deployment'
        )

        // Free text — release manager types the version to deploy
        string(
            name: 'APP_VERSION',
            defaultValue: '',
            description: 'Version to deploy — e.g. 2.4.1. Leave blank to deploy latest.'
        )

        // Checkbox — on by default, release manager can uncheck to skip
        booleanParam(
            name: 'RUN_SMOKE_TESTS',
            defaultValue: true,
            description: 'Run smoke tests after deployment completes'
        )

        // Multi-line text — optional notes for the build log
        text(
            name: 'RELEASE_NOTES',
            defaultValue: '',
            description: 'Optional release notes — shown in the build description'
        )

    }

    stages {

        stage('Validate Input') {
            steps {
                script {
                    // Fail fast if a required parameter is missing
                    // Better to catch this here than halfway through a deploy
                    if (params.APP_VERSION == '') {
                        error('APP_VERSION parameter is required — please provide a version to deploy')
                    }
                    // Set a descriptive build name visible in the Jenkins UI
                    // Makes the build history page actually useful
                    currentBuild.description = "Deploy ${params.APP_VERSION} → ${params.DEPLOY_ENV}"
                    echo "Deploying version: ${params.APP_VERSION}"
                    echo "Target environment: ${params.DEPLOY_ENV}"
                    echo "Run smoke tests: ${params.RUN_SMOKE_TESTS}"
                }
            }
        }

        stage('Deploy') {
            steps {
                echo "Starting deployment of ${params.APP_VERSION} to ${params.DEPLOY_ENV}"
                sh "./deploy.sh ${params.DEPLOY_ENV} ${params.APP_VERSION}"
            }
        }

        // This stage only runs if the RUN_SMOKE_TESTS checkbox was ticked
        // expression{} evaluates any Groovy boolean — here it reads the checkbox value
        stage('Smoke Tests') {
            when {
                expression { return params.RUN_SMOKE_TESTS == true }
            }
            steps {
                echo "Running smoke tests against ${params.DEPLOY_ENV}"
                sh "./smoke-tests.sh ${params.DEPLOY_ENV}"
            }
        }

        // This stage only runs if deploying to production
        stage('Production Health Check') {
            when {
                expression { return params.DEPLOY_ENV == 'production' }
            }
            steps {
                echo 'Running extended health checks for production deploy'
                sh './health-check.sh production --extended'
                sh "curl --fail https://api.acmecorp.com/health"
            }
        }

    }

    post {
        success {
            script {
                // Build a useful summary message using parameter values
                def notes = params.RELEASE_NOTES ? "\nRelease notes: ${params.RELEASE_NOTES}" : ''
                echo "✅ Deployed ${params.APP_VERSION} to ${params.DEPLOY_ENV} successfully.${notes}"
            }
        }
        failure {
            echo "❌ Deployment of ${params.APP_VERSION} to ${params.DEPLOY_ENV} failed"
        }
        always {
            cleanWs()
        }
    }

}