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.

[Nonary]

Note this UI is acceptable I guess, and there are some advantages particularly for 24H2 users where the encoder probing causes Sunshine to constantly throw 503 errors and require workaround scripts that essentially force the dummy plug to be activated prior to probing encoders.

However not sure if it impacts the built in display swap, I recall a commit somewhere that allowed it to work before the probing but the issue is it wouldn't be able to restore the correct monitor either way because in order to do so you have to setup a restore point essentially.

I am not sure when we will get a UI designer volunteer, but it may be months, or until AI advances to a point where it can fully automate UX design (more likely)

[sonarqubecloud]

Quality Gate failed

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

See analysis details on SonarQube Cloud

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