Fix finish/shell scripts never running in image mode (#5125)

This PR fixes `finish/shell` scripts being skipped on image-mode guests.
Finish scripts now run immediately, `prepare/shell` is unchanged.

Fixes #4917

Author: therazix

docs/releases/pending/4917.fmf

@@ -0,0 +1,4 @@
+description: |
+  The :ref:`finish shell</plugins/finish/shell>` plugin now runs
+  scripts immediately on image-mode guests instead of collecting
+  them for deferred execution that never happened.

tests/prepare/shell/test.sh

@@ -61,11 +61,7 @@ rlJournalStart
         rlPhaseStartTest "Remote Script"
             rlRun -s "tmt -vvv run provision --how=$PROVISION_HOW $image_opt prepare finish cleanup plan -n url" 0 "Prepare using a remote script"
             rlAssertGrep "Hello world" "$rlRun_LOG" #check for the prepare script
-            # TODO: #4785 Preparing from a remote script is broken in Image Mode (finish)
-            # https://github.com/teemtee/tmt/issues/4917
-            if [ "$IMAGE_MODE" != "yes" ]; then
-                rlAssertGrep "third" "$rlRun_LOG" # check for the finish script
-            fi
+            rlAssertGrep "third" "$rlRun_LOG" # check for the finish script
             assert_image_mode
         rlPhaseEnd
     done <<< "$IMAGES"

tmt/guest/__init__.py

@@ -2533,6 +2533,26 @@ def execute(
     ) -> Optional[tmt.utils.CommandOutput]:
         pass
 
+    @overload
+    def execute(
+        self,
+        command: Union[tmt.utils.Command, tmt.utils.ShellScript],
+        cwd: Optional[Path] = None,
+        environment: Optional[Environment] = None,
+        friendly_command: Optional[str] = None,
+        test_session: bool = False,
+        immediately: bool = True,
+        tty: bool = False,
+        silent: bool = False,
+        log: Optional[tmt.log.VerboseLoggingFunction] = None,
+        interactive: bool = False,
+        on_process_start: Optional[OnProcessStartCallback] = None,
+        on_process_end: Optional[OnProcessEndCallback] = None,
+        sourced_files: Optional[list[Path]] = None,
+        **kwargs: Any,
+    ) -> Optional[tmt.utils.CommandOutput]:
+        pass
+
     @abc.abstractmethod
     def execute(
         self,
@@ -2550,19 +2570,24 @@ def execute(
         on_process_end: Optional[OnProcessEndCallback] = None,
         sourced_files: Optional[list[Path]] = None,
         **kwargs: Any,
-    ) -> tmt.utils.CommandOutput:
+    ) -> Optional[tmt.utils.CommandOutput]:
         """
         Execute a command on the guest.
 
         :param command: either a command or a shell script to execute.
-        :param cwd: if set, execute command in this directory on the guest.
+        :param cwd: execute command in this directory on the guest.
         :param environment: if set, set these environment variables before running the command.
         :param friendly_command: nice, human-friendly representation of the command.
+        :param test_session: if True, this is the actual test being run.
         :param immediately: if False, the command may be collected for later
             batch execution on guests that support it (e.g., bootc guests).
             Commands with ``immediately=True`` (default) are always executed
             right away. Use ``immediately=False`` for commands that modify
             system state and can be batched (e.g., package installation).
+            When a command is deferred, ``None`` is returned instead of
+            :py:class:`CommandOutput`.
+        :returns: command output, or ``None`` if the command was deferred
+            for batch execution (when ``immediately=False`` on supported guests).
         """
 
         raise NotImplementedError
@@ -3768,6 +3793,26 @@ def execute(
     ) -> Optional[tmt.utils.CommandOutput]:
         pass
 
+    @overload
+    def execute(
+        self,
+        command: Union[tmt.utils.Command, tmt.utils.ShellScript],
+        cwd: Optional[Path] = None,
+        environment: Optional[Environment] = None,
+        friendly_command: Optional[str] = None,
+        test_session: bool = False,
+        immediately: bool = True,
+        tty: bool = False,
+        silent: bool = False,
+        log: Optional[tmt.log.VerboseLoggingFunction] = None,
+        interactive: bool = False,
+        on_process_start: Optional[OnProcessStartCallback] = None,
+        on_process_end: Optional[OnProcessEndCallback] = None,
+        sourced_files: Optional[list[Path]] = None,
+        **kwargs: Any,
+    ) -> Optional[tmt.utils.CommandOutput]:
+        pass
+
     def execute(
         self,
         command: Union[tmt.utils.Command, tmt.utils.ShellScript],

tmt/steps/finish/shell.py

@@ -44,6 +44,9 @@ class FinishShell(tmt.steps.finish.FinishPlugin[tmt.steps.finish.FinishStepData]
 
     _cloned_repo_path_envvar_name = "TMT_FINISH_SHELL_URL_REPOSITORY"
 
+    # Finish scripts must run immediately rather than being deferred.
+    _execute_immediately = True
+
     # We are reusing "prepare" step for "finish",
     # and they both have different expectations.
     # Mypy is not happy about this though.

tmt/steps/prepare/shell.py

@@ -1,5 +1,5 @@
 import threading
-from typing import Any, Optional, cast
+from typing import Any, ClassVar, Optional, cast
 
 import fmf.utils
 
@@ -109,6 +109,9 @@ class PrepareShell(tmt.steps.prepare.PreparePlugin[PrepareShellData]):
     _url_clone_lock = threading.Lock()
     _cloned_repo_path_envvar_name = 'TMT_PREPARE_SHELL_URL_REPOSITORY'
 
+    #: Whether to run scripts immediately or defer them when the guest supports it.
+    _execute_immediately: ClassVar[bool] = False
+
     @property
     def _preserved_workdir_members(self) -> set[str]:
         return {
@@ -248,7 +251,7 @@ def _invoke_script(
                 cwd=worktree,
                 environment=environment,
                 sourced_files=[self.step.plan.plan_source_script],
-                immediately=False,
+                immediately=self._execute_immediately,
             )
 
         script_queue = self.data.script[:]