- name: 3.0 - Perform Nextcloud Upgrade (Transactional)
      block:

        - name: 3.1 - Enable maintenance mode
          command: "{{ php_cli_path }} occ maintenance:mode --on"
          args:
            chdir: "{{ nextcloud_dir }}"
          become_user: "{{ nc_web_user }}"
          environment: "{{ occ_env }}"

        - name: 3.2 - Run Nextcloud CLI updater (with retry logic)
          command: "{{ php_cli_path }} updater/updater.phar --no-interaction"
          args:
            chdir: "{{ nextcloud_dir }}"
          become_user: "{{ nc_web_user }}"
          environment: "{{ occ_env }}"
          register: updater_result
          until: 
            - updater_result.rc == 0
            - "'Update successful' in updater_result.stdout or 'Nextcloud is already latest version' in updater_result.stdout"
          retries: 3
          delay: 10
          failed_when:
            - updater_result.rc != 0
            - "'Nextcloud is already latest version' not in updater_result.stdout"
        
        - name: 3.3 - Run occ upgrade
          command: "{{ php_cli_path }} occ upgrade"
          args:
            chdir: "{{ nextcloud_dir }}"
          become_user: "{{ nc_web_user }}"
          environment: "{{ occ_env }}"

        - name: 3.4 - Run optional cleanup commands
          command: "{{ item }}"
          args:
            chdir: "{{ nextcloud_dir }}"
          become_user: "{{ nc_web_user }}"
          environment: "{{ occ_env }}"
          loop:
            - "{{ php_cli_path }} occ db:add-missing-indices"
            - "{{ php_cli_path }} occ db:convert-filecache-bigint --no-interaction"
          ignore_errors: yes

        - name: 3.5 - SUCCESS – disable maintenance mode
          command: "{{ php_cli_path }} occ maintenance:mode --off"
          args:
            chdir: "{{ nextcloud_dir }}"
          become_user: "{{ nc_web_user }}"
          environment: "{{ occ_env }}"

        - name: 3.6 - Re-enable previously disabled 3rd party apps
          command: "{{ php_cli_path }} occ app:enable {{ item }}"
          args:
            chdir: "{{ nextcloud_dir }}"
          become_user: "{{ nc_web_user }}"
          environment: "{{ occ_env }}"
          loop: "{{ disabled_apps | default([]) }}"
          when: disabled_apps is defined and disabled_apps | length > 0
          ignore_errors: yes

        - name: 3.7 - Restart web service
          service:
            name: "{{ web_service_name }}"
            state: restarted

        - name: 3.8 - Verify new version
          command: "{{ php_cli_path }} occ status"
          args:
            chdir: "{{ nextcloud_dir }}"
          become_user: "{{ nc_web_user }}"
          environment: "{{ occ_env }}"
          register: occ_status_after
          changed_when: false

        - name: 3.9 - Display new version info
          debug:
            var: occ_status_after.stdout

        - name: 3.10 - Upgrade Complete
          debug:
            msg: "Nextcloud successfully upgraded!"

      rescue:

        - name: ❌ UPGRADE FAILED - Details
          debug:
            msg: |
              !!!!!!!!!!!  NEXTCLOUD UPGRADE FAILED  !!!!!!!!!!!!
              Host: {{ inventory_hostname }}
              The upgrade process encountered a fatal error.
              Maintenance mode will now be DISABLED automatically.
              Check logs:
                - {{ nextcloud_dir }}/data/updater.log
                - {{ nextcloud_dir }}/data/nextcloud.log

      always:

        - name: ALWAYS disable maintenance mode (success or failure)
          command: "{{ php_cli_path }} occ maintenance:mode --off"
          args:
            chdir: "{{ nextcloud_dir }}"
          become_user: "{{ nc_web_user }}"
          environment: "{{ occ_env }}"
          ignore_errors: yes

        - name: Final failure state (only if rescue was triggered)
          fail:
            msg: "Nextcloud upgrade failed — maintenance mode has been turned off."
          when: ansible_failed_task is defined