feat: prep commands rework

[Nonary]

Description

This pull request introduces a new event-based command system that reworks the legacy prep command system into a flexible, lifecycle-driven execution framework.

The original prep command system remains the default and recommended configuration for most users. This new model is fully opt-in and allows commands to run at precise points in the streaming lifecycle via event hooks, with fine-grained control via groups and command options.

---

⚠️ Alpha Disclaimer

• This feature is in alpha and is not ready for production or detailed code review.
• Core functionality is implemented and testable.
• Major refactoring is expected in the coming days.
• This pull request was submitted early to ensure no one spends further time working on prep command features independently.
• Please share feedback on UI/UX or overall concept only—code quality or structure is pointless to mention as it will change significantly before the final version.

---

Key Changes

Supported Events

Each command group is associated with one of the following lifecycle events:

Event	Description
PRE_STREAM_START	Before stream initialization begins
POST_STREAM_START	Immediately after stream starts
PRE_DISPLAY_CHECK	Before checking available displays
POST_DISPLAY_CHECK	After completing display checks
CLIENT_CONNECT	First client connects
ADDITIONAL_CLIENT	Extra client connects to an ongoing stream
STREAM_RESUME	Stream resumes from paused state
STREAM_PAUSE	Stream is paused
CLIENT_DISCONNECT	A client disconnects
PRE_STREAM_STOP	Before the stream stops
PRE_DISPLAY_CLEANUP	Before cleaning up displays
POST_DISPLAY_CLEANUP	After cleaning up displays
POST_STREAM_STOP	After the stream has fully stopped
ADDITIONAL_CLIENT_DISCONNECT	Extra client disconnects while others remain connected

Default Behavior & Opt-In

• The original prep command system remains in place as the default for all users.
• Opting into the new system unlocks more flexible behavior for advanced use cases.

Command System Structure

Command Groups

• Each event can define multiple command groups, evaluated in order.
• Each group has an independent failure policy that controls how errors are handled.

Group-Level Failure Policies

• FAIL_FAST: Abort remaining commands in this group on first failure
• CONTINUE_ON_FAILURE: Continue execution despite individual command failures
• FAIL_STAGE: Finish the group but skip subsequent groups if any command fails

Command Options (Per Command)

• elevated: Run with elevated/system privileges
• async: Execute the command asynchronously
• ignore_errors: Silently skip failure and continue execution

This structure supports robust, testable, and extensible automation across all major streaming lifecycle events.

Benefits

• Targeted Automation: Commands can execute exactly when needed
• Resilience: Failure modes and error tolerance are user-controlled
• Extensibility: Additional events can be added without structural redesign

---

Screenshot

Issues Fixed or Closed

• Closes Sunshine: refactor the application launch system roadmap#38

Type of Change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Dependency update (updates to dependencies)
• Documentation update (changes to documentation)
• Repository update (changes to repository files, e.g. .github/...)

Checklist

• My code follows the style guidelines of this project
• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas
• I have added or updated the in code docstring/documentation-blocks for new or existing methods/components

[Nonary]

This is the only PR I have that I suspect may never be finished, I struggled a lot of the UX design of the commands. This is out of my expertise and realistically I only see this going past draft once an experienced UI developer offers some suggestions of what we can do.

So for now, I am leaving it in draft until I get some suggestions on what we can do from UX standpoint.

[sonarqubecloud]

Quality Gate failed

Failed conditions
108 New issues
2.5% Duplication on New Code (required ≤ 2%)
10 Duplicated Blocks on New Code (required ≤ 0)
99 New Code Smells (required ≤ 0)
9 New Bugs (required ≤ 0)
C Reliability Rating on New Code (required ≥ A)

See analysis details on SonarQube Cloud

Catch issues before they fail your Quality Gate with our IDE extension SonarQube for IDE