diff --git a/.github/workflows/cpp-ci-serial-programs-base.yml b/.github/workflows/cpp-ci-serial-programs-base.yml index 58f1a9d890..86422ebd57 100644 --- a/.github/workflows/cpp-ci-serial-programs-base.yml +++ b/.github/workflows/cpp-ci-serial-programs-base.yml @@ -251,14 +251,14 @@ jobs: # The unit tests assume the downloadable resources they need are already downloaded # (see Packages/Resources/ResourceDownloadList.json). Unzip them from the Packages # checkout into where the program looks for them, DOWNLOADED_RESOURCE_PATH(): - # the working directory on Windows/Linux, and ~/Library/Application Support/SerialPrograms - # on macOS. + # the working directory on Windows/Linux, and ~/Library/Application Support/SerialPrograms/Profiles/unit-tests + # on macOS (the isolated test profile). - name: Install downloadable resources for tests if: inputs.run-tests shell: bash run: | if [[ "${{inputs.os}}" == mac* ]]; then - DOWNLOADED_RESOURCES="$HOME/Library/Application Support/SerialPrograms/DownloadedResources" + DOWNLOADED_RESOURCES="$HOME/Library/Application Support/SerialPrograms/Profiles/unit-tests/DownloadedResources" else DOWNLOADED_RESOURCES="Arduino-Source/SerialPrograms/bin/DownloadedResources" fi @@ -289,6 +289,27 @@ jobs: cd Arduino-Source/SerialPrograms/bin ./SerialPrograms --command-line-test-mode + - name: Reject unsafe lab launches (Mac) + if: startsWith(inputs.os, 'mac') && inputs.run-tests + shell: bash + run: | + cd Arduino-Source/SerialPrograms/bin + binary=./SerialPrograms.app/Contents/MacOS/SerialPrograms + expect_rejection() { + local status=0 + "$binary" "$@" || status=$? + if [[ "$status" != 2 ]]; then + echo "Expected startup rejection (2), read $status" + exit 1 + fi + } + expect_rejection --test bdsp + expect_rejection --profile + expect_rejection --profile ../lab-A + expect_rejection --command-line-test-mode --profile lab-A + # CI's default build has no PA_LAB_PROFILE: unprofiled relaunch must fail. + expect_rejection + - name: Run tests (Mac) if: startsWith(inputs.os, 'mac') && inputs.run-tests run: | diff --git a/Common/Cpp/Filesystem/Filesystem.h b/Common/Cpp/Filesystem/Filesystem.h index 21d350f014..b6cedfd202 100644 --- a/Common/Cpp/Filesystem/Filesystem.h +++ b/Common/Cpp/Filesystem/Filesystem.h @@ -22,6 +22,7 @@ #ifndef PokemonAutomation_Filesystem_Filesystem_H #define PokemonAutomation_Filesystem_Filesystem_H +#include #include #include #include "FilePath.h" @@ -115,11 +116,11 @@ Path application_install_path(); Path application_scratch_path(); -// Set a profile for program settings (/UserSettings/PROFILE_NAME/) on MacOS. -// Have to run the program with command-line argument "open -n PATH_TO_APP --args --profile PROFILE_NAME" to set the profile and launch a new window. -// This allows multiple instances of the program to run since settings are no longer shared. #if defined(__APPLE__) -void set_startup_profile(int& argc, char* argv[]); +// Set a validated macOS settings profile before any settings paths are cached. +// GUI launch uses --profile NAME or the build-bound PA_LAB_PROFILE identity. +void set_startup_profile(std::string_view profile); +// Return the identity used for the window title and scratch directory. const std::string& STARTUP_PROFILE(); #endif diff --git a/Common/Cpp/Filesystem/Filesystem_Mac.h b/Common/Cpp/Filesystem/Filesystem_Mac.h index a9dbc281ab..472233e0cc 100644 --- a/Common/Cpp/Filesystem/Filesystem_Mac.h +++ b/Common/Cpp/Filesystem/Filesystem_Mac.h @@ -21,22 +21,9 @@ namespace Filesystem{ static std::string g_startup_profile; -void set_startup_profile(int& argc, char* argv[]){ - for (int i = 1; i + 1 < argc; i++){ - if (strcmp(argv[i], "--profile") == 0){ - std::string profile = argv[i + 1]; - for (char c : profile){ - if (!(std::isalpha(c) || std::isdigit(c)) && c != u'_' && c != u'-') c = u'_'; - } - g_startup_profile = std::move(profile); - // Shift everything after --profile down by 2. - for (int j = i; j + 2 < argc; j++){ - argv[j] = argv[j + 2]; - } - argc -= 2; - return; - } - } +// Store the already-validated identity before any scratch/settings path is cached. +void set_startup_profile(std::string_view profile){ + g_startup_profile = profile; } const std::string& STARTUP_PROFILE(){ diff --git a/SerialPrograms/CMakeLists.txt b/SerialPrograms/CMakeLists.txt index 35bb597e32..812564bcff 100644 --- a/SerialPrograms/CMakeLists.txt +++ b/SerialPrograms/CMakeLists.txt @@ -203,6 +203,15 @@ if (APPLE) # https://stackoverflow.com/questions/53560288/how-to-create-a-macos-app-bundle-with-cmake # https://cmake.org/cmake/help/latest/command/add_executable.html add_executable(SerialPrograms MACOSX_BUNDLE ${SerialPrograms_ICON} ${EXECUTABLE_SOURCES}) + # Compiled identity survives Finder/TCC relaunch without command-line arguments. + set(PA_LAB_PROFILE "" CACHE STRING "Bind this lab binary to one macOS settings profile") + if(NOT PA_LAB_PROFILE STREQUAL "") + if(NOT PA_LAB_PROFILE MATCHES "^[A-Za-z0-9_][A-Za-z0-9_-]*$") + message(FATAL_ERROR "PA_LAB_PROFILE must contain only ASCII letters, digits, '_' or '-'.") + endif() + target_compile_definitions(SerialPrograms PRIVATE PA_LAB_PROFILE="${PA_LAB_PROFILE}") + endif() + set_target_properties(SerialPrograms PROPERTIES BUNDLE True MACOSX_BUNDLE_GUI_IDENTIFIER PokemonAutomation.SerialPrograms diff --git a/SerialPrograms/Source/CommonFramework/Main.cpp b/SerialPrograms/Source/CommonFramework/Main.cpp index 0e7bb7fd3f..820d7cbc04 100644 --- a/SerialPrograms/Source/CommonFramework/Main.cpp +++ b/SerialPrograms/Source/CommonFramework/Main.cpp @@ -1,5 +1,7 @@ #include +#include +#include //#include #include #include "Common/Cpp/Logging/LastLogTracker.h" @@ -38,6 +40,8 @@ #include "Logging/Logger.h" #include "Logging/OutputRedirector.h" #include "Startup/SetupSettings.h" +#include "Startup/StartupArguments.h" +#include "Startup/LabStartupPolicy.h" #include "Startup/NewVersionCheck.h" #include "Windows/MainWindow.h" #include "GlobalSettingsPanel.h" @@ -45,15 +49,14 @@ #include "PersistentSettings.h" #include "NintendoSwitch/NintendoSwitch_SettingsPanel.h" -using namespace PokemonAutomation; +Q_DECLARE_METATYPE(std::string) namespace PokemonAutomation{ - bool use_qt_ui(){ - return true; - } +bool use_qt_ui(){ + return qobject_cast(QCoreApplication::instance()) != nullptr; } -Q_DECLARE_METATYPE(std::string) +namespace{ void set_working_directory(){ const std::string app_dir = Filesystem::application_binary_directory().string_slash_normalized(); @@ -69,10 +72,6 @@ void set_working_directory(){ } } -namespace PokemonAutomation{ - - - FileLogger& global_file_logger(){ static FileLogger logger( GlobalThreadPools::unlimited_normal(), @@ -83,19 +82,12 @@ FileLogger& global_file_logger(){ return logger; } -} - int run_program(int argc, char *argv[]){ // qputenv("QT_RHI_BACKEND", "opengl"); -#if defined(__APPLE__) - Filesystem::set_startup_profile(argc, argv); - QApplication application(argc, argv); -#else QApplication application(argc, argv); -#endif #ifdef PA_DPP // Configure OpenSSL before DPP or background tasks create a TLS context. @@ -188,11 +180,6 @@ int run_program(int argc, char *argv[]){ - ScopeExit cleanup([]{ - SerialPortPoller::instance().stop(); - GlobalMediaServices::instance().stop(); - }); - // Several novice developers struggled to build and run the program due to missing Resources folder. // Add this check to pop a message box when Resources folder is missing. if (!check_resource_folder(logger)){ @@ -208,34 +195,22 @@ int run_program(int argc, char *argv[]){ logger.log(error.message(), COLOR_RED); } - // Load the Switch framework settings now, not only when their panel is opened. - OptionsPanelWrapper().make_panel()->load_json_from_global(); - - // Preload a bunch of stuff now so they are ready later. - SerialPortPoller::instance().ports(); - get_all_cameras(); - - // Force all the Qt thread pools to be constructed now on the main thread. + // Persisted test mode also exits before console options, devices or a window. GlobalThreadPools::qt_worker_threadpool(); GlobalThreadPools::qt_event_threadpool(); - - bool augment_test_color_distortions = false; - for (size_t i = 0; i < argc; i++){ - constexpr const char* force_run_tests = "--command-line-test-mode"; - constexpr const char* distort_test_images = "--augment-color-distortions"; - - if (strcmp(argv[i], force_run_tests) == 0){ - GlobalSettings::instance().COMMAND_LINE_TEST_MODE = true; - } - if (strcmp(argv[i], distort_test_images) == 0){ - augment_test_color_distortions = true; - } - } - if (GlobalSettings::instance().COMMAND_LINE_TEST_MODE){ - return run_command_line_tests(augment_test_color_distortions); + return run_command_line_tests(false); } + ScopeExit cleanup([]{ + SerialPortPoller::instance().stop(); + GlobalMediaServices::instance().stop(); + }); + + OptionsPanelWrapper().make_panel()->load_json_from_global(); + SerialPortPoller::instance().ports(); + get_all_cameras(); + // Check whether the hardware is powerful enough to run this program. if (!check_hardware()){ return 1; @@ -280,29 +255,8 @@ int run_program(int argc, char *argv[]){ } -int main(int argc, char *argv[]){ -#if 0 - // Retrieve and store program name - set_program_path(argv[0]); -#endif - -#if defined(__linux__) - // Qt multimedia, default to gstreamer to prevent flickering - // Easier than the alternative which is compiling qt6multimedia with QT_DEFAULT_MEDIA_BACKEND - // See: https://doc.qt.io/qt-6.5/qtmultimedia-index.html - if (qEnvironmentVariableIsEmpty("QT_MEDIA_BACKEND")){ - qputenv("QT_MEDIA_BACKEND", "gstreamer"); - } -#endif - - // So far, this is only needed on Mac where static initialization is fucked up. - PokemonAutomation::register_all_statics(); - - setup_crash_handler(); - - int ret = run_program(argc, argv); - - +// Stop GUI services after run_program() returns, preserving the existing order. +void stop_application_services(){ #ifdef PA_SOCIAL_SDK Integration::DiscordSocialSDK::DiscordSocial::instance().stop(); #endif @@ -325,6 +279,47 @@ int main(int argc, char *argv[]){ global_watchdog().stop(); global_file_logger().stop(); +} + +// Join the worker pools after service shutdown and the Windows Qt workaround. +void stop_thread_pools(){ + // Force stop the thread pools. + // This is where all the threads in the program are joined. + PokemonAutomation::GlobalThreadPools::computation_realtime().stop(); + PokemonAutomation::GlobalThreadPools::computation_normal().stop(); + PokemonAutomation::GlobalThreadPools::unlimited_realtime().stop(); + PokemonAutomation::GlobalThreadPools::unlimited_normal().stop(); + PokemonAutomation::global_dispatcher.stop(); + + GlobalThreadPools::qt_worker_threadpool().stop(); + GlobalThreadPools::qt_event_threadpool().stop(); + +} + +int run_gui_application(int argc, char *argv[]){ +#if 0 + // Retrieve and store program name + set_program_path(argv[0]); +#endif + +#if defined(__linux__) + // Qt multimedia, default to gstreamer to prevent flickering + // Easier than the alternative which is compiling qt6multimedia with QT_DEFAULT_MEDIA_BACKEND + // See: https://doc.qt.io/qt-6.5/qtmultimedia-index.html + if (qEnvironmentVariableIsEmpty("QT_MEDIA_BACKEND")){ + qputenv("QT_MEDIA_BACKEND", "gstreamer"); + } +#endif + + // So far, this is only needed on Mac where static initialization is fucked up. + PokemonAutomation::register_all_statics(); + + setup_crash_handler(); + + int ret = run_program(argc, argv); + + + stop_application_services(); // // Workaround Qt 6.9 thread-adoption bug on Windows. // https://github.com/PokemonAutomation/Arduino-Source/issues/570 @@ -337,18 +332,73 @@ int main(int argc, char *argv[]){ std::quick_exit(ret); #endif - // Force stop the thread pools. - // This is where all the threads in the program are joined. - PokemonAutomation::GlobalThreadPools::computation_realtime().stop(); - PokemonAutomation::GlobalThreadPools::computation_normal().stop(); - PokemonAutomation::GlobalThreadPools::unlimited_realtime().stop(); - PokemonAutomation::GlobalThreadPools::unlimited_normal().stop(); - PokemonAutomation::global_dispatcher.stop(); - - GlobalThreadPools::qt_worker_threadpool().stop(); - GlobalThreadPools::qt_event_threadpool().stop(); + stop_thread_pools(); std::cout << "Exiting main()..." << std::endl; return ret; } + +// Explicit tests use QCoreApplication and never enter GUI/settings/device startup. +int run_test_application(int argc, char* argv[], const StartupPlan& plan){ +#if defined(__APPLE__) + Filesystem::set_startup_profile("unit-tests"); +#endif + QCoreApplication application(argc, argv); + register_all_statics(); + GlobalThreadPools::qt_worker_threadpool(); + GlobalThreadPools::qt_event_threadpool(); + const int ret = run_command_line_tests(plan.augment_color_distortions); + OCR::clear_ocr_cache(); + global_periodic_runner().stop(); + global_watchdog().stop(); +#ifdef PA_ENABLE_QT_ADOPTION_WORKAROUND + std::quick_exit(ret); +#endif + stop_thread_pools(); + return ret; +} + +} // namespace +} // namespace PokemonAutomation + +// Validate before even constructing Qt: a typo must never become a hardware launch. +int main(int argc, char* argv[]){ + std::vector arguments; + for (int i = 1; i < argc; i++){ + arguments.emplace_back(argv[i]); + } + PokemonAutomation::LabStartupPolicy policy; +#if defined(__APPLE__) + policy.profiles = PokemonAutomation::LabProfileMode::REQUIRED; +#ifdef PA_LAB_PROFILE + policy.bound_profile = PA_LAB_PROFILE; +#endif +#endif + const PokemonAutomation::StartupPlan plan = PokemonAutomation::apply_lab_startup_policy(PokemonAutomation::parse_startup_arguments(arguments), policy); + if (plan.mode == PokemonAutomation::StartupMode::REJECTED){ + std::cerr << plan.error << std::endl; + } + // Keep backing storage alive for Qt, which may mutate argc and argv. + std::vector qt_storage = plan.qt_arguments; + qt_storage.insert(qt_storage.begin(), argv[0]); + std::vector qt_argv; + for (std::string& arg : qt_storage){ + qt_argv.push_back(arg.data()); + } + int qt_argc = (int)qt_argv.size(); + qt_argv.push_back(nullptr); + return PokemonAutomation::dispatch_startup(plan, { + .gui = [&](const PokemonAutomation::StartupPlan& selected){ +#if defined(__APPLE__) + PokemonAutomation::Filesystem::set_startup_profile(*selected.profile); +#else + (void)selected; +#endif + return PokemonAutomation::run_gui_application(qt_argc, qt_argv.data()); + }, + .tests = [&](const PokemonAutomation::StartupPlan& selected){ + return PokemonAutomation::run_test_application(qt_argc, qt_argv.data(), selected); + }, + }); +} diff --git a/SerialPrograms/Source/CommonFramework/Startup/LabStartupPolicy.cpp b/SerialPrograms/Source/CommonFramework/Startup/LabStartupPolicy.cpp new file mode 100644 index 0000000000..a9f1339ca4 --- /dev/null +++ b/SerialPrograms/Source/CommonFramework/Startup/LabStartupPolicy.cpp @@ -0,0 +1,32 @@ +/* Lab Startup Policy + * + * From: https://github.com/PokemonAutomation/ + */ +#include "LabStartupPolicy.h" + +namespace PokemonAutomation{ + +StartupPlan apply_lab_startup_policy(StartupPlan plan, const LabStartupPolicy& policy){ + if (plan.mode != StartupMode::GUI){ + return plan; + } + if (policy.profiles == LabProfileMode::UNSUPPORTED){ + if (plan.profile || policy.bound_profile){ + return {.error = "Settings profiles are supported only on macOS."}; + } + return plan; + } + if (policy.bound_profile){ + if (!valid_startup_profile(*policy.bound_profile) || + (plan.profile && plan.profile != policy.bound_profile)){ + return {.error = "The requested profile does not match this lab build."}; + } + plan.profile = policy.bound_profile; + } + if (!plan.profile){ + return {.error = "Lab launch requires --profile NAME or a build configured with PA_LAB_PROFILE."}; + } + return plan; +} + +} // namespace PokemonAutomation diff --git a/SerialPrograms/Source/CommonFramework/Startup/LabStartupPolicy.h b/SerialPrograms/Source/CommonFramework/Startup/LabStartupPolicy.h new file mode 100644 index 0000000000..f8566c3998 --- /dev/null +++ b/SerialPrograms/Source/CommonFramework/Startup/LabStartupPolicy.h @@ -0,0 +1,25 @@ +/* Lab Startup Policy + * + * From: https://github.com/PokemonAutomation/ + */ +#ifndef PokemonAutomation_LabStartupPolicy_H +#define PokemonAutomation_LabStartupPolicy_H +#include "StartupArguments.h" + +namespace PokemonAutomation{ + +// Profiles are supported by the macOS settings backend, and required for lab GUIs. +enum class LabProfileMode{UNSUPPORTED, REQUIRED}; + +// Lab-only restrictions, independent of the general application argument grammar. +struct LabStartupPolicy{ + LabProfileMode profiles = LabProfileMode::UNSUPPORTED; + std::optional bound_profile = std::nullopt; +}; + +// Apply lab identity restrictions after parsing. Rejected plans stay rejected; +// tests bypass console identity, while GUI launches must satisfy the lab policy. +StartupPlan apply_lab_startup_policy(StartupPlan plan, const LabStartupPolicy& policy); + +} // namespace PokemonAutomation +#endif diff --git a/SerialPrograms/Source/CommonFramework/Startup/LabStartupPolicy_Tests.cpp b/SerialPrograms/Source/CommonFramework/Startup/LabStartupPolicy_Tests.cpp new file mode 100644 index 0000000000..5581e264a0 --- /dev/null +++ b/SerialPrograms/Source/CommonFramework/Startup/LabStartupPolicy_Tests.cpp @@ -0,0 +1,139 @@ +/* Lab Startup Tests + * + * From: https://github.com/PokemonAutomation/ + * + * Regression context: fork PR #226, 01e665911, lab controller/permissions lesson. + * A typo in a test command must never restore a saved controller panel. + */ +#include +#include +#include "LabStartupPolicy.h" +#include "LabStartupPolicy_Tests.h" + +namespace PokemonAutomation{ +namespace{ + +struct LabStartupInput{ + std::string_view name; + std::vector arguments; + LabStartupPolicy policy; +}; + +struct LabStartupExpectation{ + StartupMode mode; + std::optional profile = std::nullopt; + bool augment = false; + int gui_calls = 0; + int test_calls = 0; + int exit_code = 2; + std::vector qt_arguments = {}; +}; + +struct LabStartupCase{ + LabStartupInput input; + LabStartupExpectation expectation; +}; + +const LabStartupCase LAB_STARTUP_CASES[] = { + {.input = {.name = "unbound relaunch", .arguments = {}, .policy = {LabProfileMode::REQUIRED}}, + .expectation = {.mode = StartupMode::REJECTED}}, + {.input = {.name = "bound relaunch", .arguments = {}, .policy = {LabProfileMode::REQUIRED, "lab-B"}}, + .expectation = {.mode = StartupMode::GUI, .profile = "lab-B", .gui_calls = 1, .exit_code = 17}}, + {.input = {.name = "explicit identity", .arguments = {"--profile", "lab-B"}, .policy = {LabProfileMode::REQUIRED}}, + .expectation = {.mode = StartupMode::GUI, .profile = "lab-B", .gui_calls = 1, .exit_code = 17}}, + {.input = {.name = "matching identity", .arguments = {"--profile", "lab-B"}, .policy = {LabProfileMode::REQUIRED, "lab-B"}}, + .expectation = {.mode = StartupMode::GUI, .profile = "lab-B", .gui_calls = 1, .exit_code = 17}}, + {.input = {.name = "wrong console", .arguments = {"--profile", "lab-A"}, .policy = {LabProfileMode::REQUIRED, "lab-B"}}, + .expectation = {.mode = StartupMode::REJECTED}}, + {.input = {.name = "missing profile", .arguments = {"--profile"}, .policy = {LabProfileMode::REQUIRED}}, + .expectation = {.mode = StartupMode::REJECTED}}, + {.input = {.name = "empty profile", .arguments = {"--profile", ""}, .policy = {LabProfileMode::REQUIRED}}, + .expectation = {.mode = StartupMode::REJECTED}}, + {.input = {.name = "duplicate profile", .arguments = {"--profile", "lab-B", "--profile", "lab-B"}, .policy = {LabProfileMode::REQUIRED}}, + .expectation = {.mode = StartupMode::REJECTED}}, + {.input = {.name = "path traversal", .arguments = {"--profile", "../lab-A"}, .policy = {LabProfileMode::REQUIRED}}, + .expectation = {.mode = StartupMode::REJECTED}}, + {.input = {.name = "absolute profile", .arguments = {"--profile", "/lab-A"}, .policy = {LabProfileMode::REQUIRED}}, + .expectation = {.mode = StartupMode::REJECTED}}, + {.input = {.name = "space in profile", .arguments = {"--profile", "lab B"}, .policy = {LabProfileMode::REQUIRED}}, + .expectation = {.mode = StartupMode::REJECTED}}, + {.input = {.name = "unicode profile", .arguments = {"--profile", "lab-é"}, .policy = {LabProfileMode::REQUIRED}}, + .expectation = {.mode = StartupMode::REJECTED}}, + {.input = {.name = "option as profile", .arguments = {"--profile", "--command-line-test-mode"}, .policy = {LabProfileMode::REQUIRED}}, + .expectation = {.mode = StartupMode::REJECTED}}, + {.input = {.name = "test typo from incident", .arguments = {"--test", "bdsp"}, .policy = {LabProfileMode::REQUIRED, "lab-B"}}, + .expectation = {.mode = StartupMode::REJECTED}}, + {.input = {.name = "unknown after test flag", .arguments = {"--command-line-test-mode", "bdsp"}, .policy = {}}, + .expectation = {.mode = StartupMode::REJECTED}}, + {.input = {.name = "unsupported filter", .arguments = {"--command-line-test-mode", "--test-filter=bdsp"}, .policy = {}}, + .expectation = {.mode = StartupMode::REJECTED}}, + {.input = {.name = "test bypasses profile requirement", .arguments = {"--command-line-test-mode"}, .policy = {LabProfileMode::REQUIRED}}, + .expectation = {.mode = StartupMode::TESTS, .test_calls = 1, .exit_code = 23}}, + {.input = {.name = "test bypasses bound console", .arguments = {"--command-line-test-mode"}, .policy = {LabProfileMode::REQUIRED, "lab-B"}}, + .expectation = {.mode = StartupMode::TESTS, .test_calls = 1, .exit_code = 23}}, + {.input = {.name = "augmented tests", .arguments = {"--augment-color-distortions", "--command-line-test-mode"}, .policy = {}}, + .expectation = {.mode = StartupMode::TESTS, .augment = true, .test_calls = 1, .exit_code = 23}}, + {.input = {.name = "augmentation without tests", .arguments = {"--augment-color-distortions"}, .policy = {}}, + .expectation = {.mode = StartupMode::REJECTED}}, + {.input = {.name = "tests cannot select live profile", .arguments = {"--command-line-test-mode", "--profile", "lab-A"}, .policy = {LabProfileMode::REQUIRED}}, + .expectation = {.mode = StartupMode::REJECTED}}, + {.input = {.name = "non mac GUI unchanged", .arguments = {}, .policy = {}}, + .expectation = {.mode = StartupMode::GUI, .gui_calls = 1, .exit_code = 17}}, + {.input = {.name = "unsupported profile platform", .arguments = {"--profile", "lab-B"}, .policy = {}}, + .expectation = {.mode = StartupMode::REJECTED}}, + {.input = {.name = "invalid build identity", .arguments = {}, .policy = {LabProfileMode::REQUIRED, "../lab-A"}}, + .expectation = {.mode = StartupMode::REJECTED}}, +}; + +// The GUI callback represents settings load, window restoration and hardware discovery. +// A rejected or test launch must never reach it, even when a saved panel has devices. +UnitTestResult check_lab_startup_case(const LabStartupCase& test){ + const StartupPlan plan = apply_lab_startup_policy(parse_startup_arguments(test.input.arguments), test.input.policy); + const LabStartupExpectation& expected = test.expectation; + if (plan.mode != expected.mode || plan.profile != expected.profile || + plan.augment_color_distortions != expected.augment){ + return std::format("Expected mode {}, profile {}, augment {}; read mode {}, profile {}, augment {}.", + (int)expected.mode, expected.profile.value_or(""), expected.augment, + (int)plan.mode, plan.profile.value_or(""), plan.augment_color_distortions); + } + if (plan.qt_arguments != expected.qt_arguments){ + return "Expected Qt argument sequence differs from the preserved sequence."; + } + if ((plan.mode == StartupMode::REJECTED) != !plan.error.empty()){ + return "Expected rejection reason exactly when startup is rejected."; + } + int gui_calls = 0; + int test_calls = 0; + const int code = dispatch_startup(plan, { + .gui = [&](const StartupPlan&){ gui_calls++; return 17; }, + .tests = [&](const StartupPlan&){ test_calls++; return 23; }, + }); + if (gui_calls != expected.gui_calls || test_calls != expected.test_calls || code != expected.exit_code){ + return std::format("Expected GUI calls {}, test calls {}, exit {}; read GUI calls {}, test calls {}, exit {}.", + expected.gui_calls, expected.test_calls, expected.exit_code, gui_calls, test_calls, code); + } + return true; +} + +class LabStartupTest : public UnitTest{ +public: + explicit LabStartupTest(const LabStartupCase& test) + : UnitTest("Startup/LabPolicy/" + std::string(test.input.name)) + , m_test(test) + {} + virtual UnitTestResult run(Logger&, CancellableScope&) const override{ + return check_lab_startup_case(m_test); + } +private: + const LabStartupCase& m_test; +}; + +} // namespace + +void add_tests_LabStartupPolicy(UnitTestDatabase& database){ + for (const LabStartupCase& test : LAB_STARTUP_CASES){ + database.add(test); + } +} + +} // namespace PokemonAutomation diff --git a/SerialPrograms/Source/CommonFramework/Startup/LabStartupPolicy_Tests.h b/SerialPrograms/Source/CommonFramework/Startup/LabStartupPolicy_Tests.h new file mode 100644 index 0000000000..786ab3fdc9 --- /dev/null +++ b/SerialPrograms/Source/CommonFramework/Startup/LabStartupPolicy_Tests.h @@ -0,0 +1,15 @@ +/* Lab Startup Tests + * + * From: https://github.com/PokemonAutomation/ + */ +#ifndef PokemonAutomation_LabStartupPolicy_Tests_H +#define PokemonAutomation_LabStartupPolicy_Tests_H +#include "Common/Cpp/TestRunners/UnitTestDatabase.h" + +namespace PokemonAutomation{ + +// Register lab-policy and startup-dispatch regressions; no Qt or hardware is opened. +void add_tests_LabStartupPolicy(UnitTestDatabase& database); + +} // namespace PokemonAutomation +#endif diff --git a/SerialPrograms/Source/CommonFramework/Startup/StartupArguments.cpp b/SerialPrograms/Source/CommonFramework/Startup/StartupArguments.cpp new file mode 100644 index 0000000000..e272e05991 --- /dev/null +++ b/SerialPrograms/Source/CommonFramework/Startup/StartupArguments.cpp @@ -0,0 +1,97 @@ +/* Application Startup Arguments + * + * From: https://github.com/PokemonAutomation/ + */ +#include +#include "StartupArguments.h" + +namespace PokemonAutomation{ +// Profile names are single ASCII path components; never silently rewrite an identity. +bool valid_startup_profile(std::string_view profile){ + return !profile.empty() && profile.front() != '-' && std::ranges::all_of(profile, [](char c){ + return (c >= 'a' && c <= 'z') || (c >= 'A' && c <= 'Z') || + (c >= '0' && c <= '9') || c == '_' || c == '-'; + }); +} + +namespace{ + +// Qt owns option values; recognize only its documented application option spellings. +// References: doc.qt.io/qt-6/{qapplication,qguiapplication}.html constructors. +enum class QtArgument{UNKNOWN, ACCEPTED, INVALID}; +QtArgument consume_qt_argument(std::span arguments, size_t& index, StartupPlan& plan){ + const std::string_view arg = arguments[index]; + if (arg == "-reverse" || arg == "-widgetcount"){ + plan.qt_arguments.emplace_back(arg); + return QtArgument::ACCEPTED; + } + constexpr std::string_view VALUE_OPTIONS[] = { + "-platform", "-platformpluginpath", "-platformtheme", "-plugin", + "-qwindowgeometry", "-qwindowicon", "-qwindowtitle", "-session", + "-display", "-geometry", "-style", "-stylesheet", + }; + if (std::ranges::find(VALUE_OPTIONS, arg) != std::end(VALUE_OPTIONS)){ + if (index + 1 == arguments.size() || arguments[index + 1].empty() || + arguments[index + 1].starts_with('-')){ + return QtArgument::INVALID; + } + plan.qt_arguments.emplace_back(arg); + plan.qt_arguments.emplace_back(arguments[++index]); + return QtArgument::ACCEPTED; + } + for (std::string_view prefix : {"-style=", "-stylesheet=", "-qmljsdebugger="}){ + if (arg.starts_with(prefix)){ + if (arg.size() == prefix.size()){ + return QtArgument::INVALID; + } + plan.qt_arguments.emplace_back(arg); + return QtArgument::ACCEPTED; + } + } + return QtArgument::UNKNOWN; +} + +} // namespace + +StartupPlan parse_startup_arguments(std::span arguments){ + StartupPlan plan{.mode = StartupMode::GUI}; + for (size_t i = 0; i < arguments.size(); i++){ + const std::string_view arg = arguments[i]; + if (arg == "--profile"){ + if (plan.profile || i + 1 == arguments.size() || !valid_startup_profile(arguments[i + 1])){ + return {.error = "--profile requires one unique name containing only ASCII letters, digits, '_' or '-' (not starting with '-')."}; + } + plan.profile = arguments[++i]; + }else if (arg == "--command-line-test-mode"){ + plan.mode = StartupMode::TESTS; + }else if (arg == "--augment-color-distortions"){ + plan.augment_color_distortions = true; + }else{ + const QtArgument result = consume_qt_argument(arguments, i, plan); + if (result != QtArgument::ACCEPTED){ + return {.error = "Unknown or incomplete startup argument: " + std::string(arg)}; + } + } + } + if (plan.augment_color_distortions && plan.mode != StartupMode::TESTS){ + return {.error = "--augment-color-distortions requires --command-line-test-mode."}; + } + if (plan.mode == StartupMode::TESTS && plan.profile){ + return {.error = "Test launches cannot select a console profile."}; + } + return plan; +} + +int dispatch_startup(const StartupPlan& plan, const StartupHandlers& handlers){ + switch (plan.mode){ + case StartupMode::GUI: + return handlers.gui(plan); + case StartupMode::TESTS: + return handlers.tests(plan); + case StartupMode::REJECTED: + return 2; + } + return 2; +} + +} // namespace PokemonAutomation diff --git a/SerialPrograms/Source/CommonFramework/Startup/StartupArguments.h b/SerialPrograms/Source/CommonFramework/Startup/StartupArguments.h new file mode 100644 index 0000000000..895b4345d3 --- /dev/null +++ b/SerialPrograms/Source/CommonFramework/Startup/StartupArguments.h @@ -0,0 +1,49 @@ +/* Application Startup Arguments + * + * From: https://github.com/PokemonAutomation/ + * + * Parse before Qt, settings, logging or device discovery. Example: + * open -n SerialPrograms.app --args --profile lab-B + */ +#ifndef PokemonAutomation_StartupArguments_H +#define PokemonAutomation_StartupArguments_H + +#include +#include +#include +#include +#include +#include + +namespace PokemonAutomation{ + +// Rejected launches must not enter either application entry point. +enum class StartupMode{REJECTED, GUI, TESTS}; + +// Validated startup intent; error describes a rejected launch. +struct StartupPlan{ + StartupMode mode = StartupMode::REJECTED; + std::optional profile = std::nullopt; + bool augment_color_distortions = false; + std::string error = {}; + std::vector qt_arguments = {}; +}; + +// Check a single ASCII profile path component without rewriting its identity. +bool valid_startup_profile(std::string_view profile); + +// Parse argv without argv[0]; preserve documented Qt options for Qt to interpret. +// Unknown or malformed application/Qt arguments fail before settings or devices. +StartupPlan parse_startup_arguments(std::span arguments); + +// Application entry points: the GUI callback owns all settings and hardware startup. +struct StartupHandlers{ + std::function gui; + std::function tests; +}; + +// Dispatch a validated plan. Rejection returns 2 without invoking either callback. +int dispatch_startup(const StartupPlan& plan, const StartupHandlers& handlers); + +} // namespace PokemonAutomation +#endif diff --git a/SerialPrograms/Source/CommonFramework/Startup/StartupArguments_Tests.cpp b/SerialPrograms/Source/CommonFramework/Startup/StartupArguments_Tests.cpp new file mode 100644 index 0000000000..bae0d6f3fc --- /dev/null +++ b/SerialPrograms/Source/CommonFramework/Startup/StartupArguments_Tests.cpp @@ -0,0 +1,98 @@ +/* Application Startup Argument Tests + * + * From: https://github.com/PokemonAutomation/ + */ +#include +#include "StartupArguments.h" +#include "StartupArguments_Tests.h" + +namespace PokemonAutomation{ +namespace{ + +struct ArgumentInput{ + std::string_view name; + std::vector arguments; +}; + +struct ArgumentExpectation{ + StartupMode mode; + std::optional profile = std::nullopt; + std::vector qt_arguments = {}; +}; + +struct ArgumentCase{ + ArgumentInput input; + ArgumentExpectation expectation; +}; + +const ArgumentCase ARGUMENT_CASES[] = { + {.input = {.name = "ordinary GUI", .arguments = {}}, + .expectation = {.mode = StartupMode::GUI}}, + {.input = {.name = "optional profile", .arguments = {"--profile", "lab-B"}}, + .expectation = {.mode = StartupMode::GUI, .profile = "lab-B"}}, + {.input = {.name = "test dispatch", .arguments = {"--command-line-test-mode"}}, + .expectation = {.mode = StartupMode::TESTS}}, + {.input = {.name = "Qt platform", .arguments = {"-platform", "offscreen"}}, + .expectation = {.mode = StartupMode::GUI, .qt_arguments = {"-platform", "offscreen"}}}, + {.input = {.name = "Qt style assignment", .arguments = {"-style=Fusion"}}, + .expectation = {.mode = StartupMode::GUI, .qt_arguments = {"-style=Fusion"}}}, + {.input = {.name = "Qt style pair", .arguments = {"-style", "Fusion"}}, + .expectation = {.mode = StartupMode::GUI, .qt_arguments = {"-style", "Fusion"}}}, + {.input = {.name = "Qt stylesheet assignment", .arguments = {"-stylesheet=some path.qss"}}, + .expectation = {.mode = StartupMode::GUI, .qt_arguments = {"-stylesheet=some path.qss"}}}, + {.input = {.name = "Qt flags and application profile", .arguments = {"-reverse", "--profile", "lab-B", "-widgetcount"}}, + .expectation = {.mode = StartupMode::GUI, .profile = "lab-B", .qt_arguments = {"-reverse", "-widgetcount"}}}, + {.input = {.name = "repeated Qt plugin", .arguments = {"-plugin", "one", "-plugin", "two"}}, + .expectation = {.mode = StartupMode::GUI, .qt_arguments = {"-plugin", "one", "-plugin", "two"}}}, + {.input = {.name = "Qt missing value", .arguments = {"-platform"}}, + .expectation = {.mode = StartupMode::REJECTED}}, + {.input = {.name = "Qt empty value", .arguments = {"-style", ""}}, + .expectation = {.mode = StartupMode::REJECTED}}, + {.input = {.name = "Qt empty assignment", .arguments = {"-style="}}, + .expectation = {.mode = StartupMode::REJECTED}}, + {.input = {.name = "Qt must not swallow application option", .arguments = {"-platform", "--command-line-test-mode"}}, + .expectation = {.mode = StartupMode::REJECTED}}, + {.input = {.name = "Qt must not swallow typo", .arguments = {"-platform", "--test", "bdsp"}}, + .expectation = {.mode = StartupMode::REJECTED}}, + {.input = {.name = "unknown Qt-looking option", .arguments = {"-platfrom", "offscreen"}}, + .expectation = {.mode = StartupMode::REJECTED}}, + {.input = {.name = "unknown after valid Qt option", .arguments = {"-reverse", "--test", "bdsp"}}, + .expectation = {.mode = StartupMode::REJECTED}}, +}; + +UnitTestResult check_argument_case(const ArgumentCase& test){ + const StartupPlan plan = parse_startup_arguments(test.input.arguments); + const ArgumentExpectation& expected = test.expectation; + if (plan.mode != expected.mode || plan.profile != expected.profile){ + return std::format("Expected mode {} and profile {}; read mode {} and profile {}.", + (int)expected.mode, expected.profile.value_or(""), + (int)plan.mode, plan.profile.value_or("")); + } + if (plan.qt_arguments != expected.qt_arguments){ + return "Expected the complete Qt argument sequence to be preserved in order."; + } + return true; +} + +class ArgumentTest : public UnitTest{ +public: + explicit ArgumentTest(const ArgumentCase& test) + : UnitTest("Startup/Arguments/" + std::string(test.input.name)) + , m_test(test) + {} + virtual UnitTestResult run(Logger&, CancellableScope&) const override{ + return check_argument_case(m_test); + } +private: + const ArgumentCase& m_test; +}; + +} // namespace + +void add_tests_StartupArguments(UnitTestDatabase& database){ + for (const ArgumentCase& test : ARGUMENT_CASES){ + database.add(test); + } +} + +} // namespace PokemonAutomation diff --git a/SerialPrograms/Source/CommonFramework/Startup/StartupArguments_Tests.h b/SerialPrograms/Source/CommonFramework/Startup/StartupArguments_Tests.h new file mode 100644 index 0000000000..665e0bed7a --- /dev/null +++ b/SerialPrograms/Source/CommonFramework/Startup/StartupArguments_Tests.h @@ -0,0 +1,15 @@ +/* Lab Startup Tests + * + * From: https://github.com/PokemonAutomation/ + */ +#ifndef PokemonAutomation_StartupArguments_Tests_H +#define PokemonAutomation_StartupArguments_Tests_H +#include "Common/Cpp/TestRunners/UnitTestDatabase.h" + +namespace PokemonAutomation{ + +// Register parser and startup-dispatch regressions; no Qt or hardware is opened. +void add_tests_StartupArguments(UnitTestDatabase& database); + +} // namespace PokemonAutomation +#endif diff --git a/SerialPrograms/Source/ComputerPrograms/ComputerPrograms_UnitTestRunner.cpp b/SerialPrograms/Source/ComputerPrograms/ComputerPrograms_UnitTestRunner.cpp index b4ff93e7f1..c31934af2e 100644 --- a/SerialPrograms/Source/ComputerPrograms/ComputerPrograms_UnitTestRunner.cpp +++ b/SerialPrograms/Source/ComputerPrograms/ComputerPrograms_UnitTestRunner.cpp @@ -22,6 +22,8 @@ #include "CommonFramework/ProgramStats/StatsTracking.h" #include "CommonFramework/Tools/GlobalThreadPools.h" #include "CommonFramework/Windows/LabChannel_Tests.h" +#include "CommonFramework/Startup/StartupArguments_Tests.h" +#include "CommonFramework/Startup/LabStartupPolicy_Tests.h" #include "CommonTools/VisualDetectors/BlackBorderDetector.h" #include "CommonTools/OCR/OCR_Tests.h" @@ -63,6 +65,8 @@ UnitTestDatabase make_UNIT_TESTS_ALL(){ add_tests_SinkPipeline(ret); add_tests_AudioFileLoader(ret); add_tests_LabChannel(ret); + add_tests_StartupArguments(ret); + add_tests_LabStartupPolicy(ret); OCR::add_tests(ret); Kernels::add_tests(ret); NintendoSwitch::add_tests_CheckOnlineDetector(ret); diff --git a/SerialPrograms/cmake/SourceFiles.cmake b/SerialPrograms/cmake/SourceFiles.cmake index 05a0d18f4a..7b51d92e21 100644 --- a/SerialPrograms/cmake/SourceFiles.cmake +++ b/SerialPrograms/cmake/SourceFiles.cmake @@ -717,6 +717,14 @@ file(GLOB LIBRARY_SOURCES Source/CommonFramework/Startup/NewVersionCheck.h Source/CommonFramework/Startup/SetupSettings.cpp Source/CommonFramework/Startup/SetupSettings.h + Source/CommonFramework/Startup/StartupArguments.cpp + Source/CommonFramework/Startup/StartupArguments.h + Source/CommonFramework/Startup/LabStartupPolicy.cpp + Source/CommonFramework/Startup/LabStartupPolicy.h + Source/CommonFramework/Startup/LabStartupPolicy_Tests.cpp + Source/CommonFramework/Startup/LabStartupPolicy_Tests.h + Source/CommonFramework/Startup/StartupArguments_Tests.cpp + Source/CommonFramework/Startup/StartupArguments_Tests.h Source/CommonFramework/Tools/DebugDumper.cpp Source/CommonFramework/Tools/DebugDumper.h Source/CommonFramework/Tools/ErrorDumper.cpp diff --git a/devtools/lab/README.md b/devtools/lab/README.md index a065bfea88..8dc1560664 100644 --- a/devtools/lab/README.md +++ b/devtools/lab/README.md @@ -38,9 +38,10 @@ rules are cheap; use both. `PROFILE` is the app's user-files folder: the one with `SerialPrograms.log`, `Screenshots/` and the settings. On macOS it is -`~/Library/Application Support/SerialPrograms`, or -`.../SerialPrograms/Profiles/NAME` for an app launched with -`--args --profile NAME`. On Windows and Linux it is the folder the app was +`~/Library/Application Support/SerialPrograms/Profiles/NAME` for a lab app +launched with `--args --profile NAME` or built with `PA_LAB_PROFILE=NAME`. +Lab builds refuse an unprofiled macOS GUI launch; they never fall back to the +live app's default settings directory. On Windows and Linux it is the folder the app was started in. `labctl.sh supports BUILD` says whether a build has the channel at all. @@ -71,8 +72,68 @@ touched. On macOS: and capture device (the `ConsoleSetup` of each program in the settings file), so two lab apps drive two consoles at once. -On Windows and Linux the separate copy is just a second folder, and the -profile flag is the same. +On Windows and Linux the separate copy is a second folder; `--profile` is +unsupported and rejected. + +## Startup isolation and tests + +Bind each deployed macOS lab binary to its console when configuring its existing +build directory, for example: + +```sh +cmake -S SerialPrograms -B /path/to/build -DPA_LAB_PROFILE=lab-B +``` + +This compiles the identity into the executable. Finder and macOS permission-dialog +relaunches need no arguments and still select `Profiles/lab-B`. An explicit +`--profile lab-A` against that binary exits with status 2 before Qt, settings, +logging or device discovery. Changing the bundle's name or identifier does not +change its compiled profile; build each console's binary with the correct value. +The existing signing/bundle-identity procedure still applies. + +With `PA_LAB_PROFILE` empty (the build default), macOS GUI startup requires +`--profile NAME`; a no-argument relaunch safely exits. Names are ASCII letters, +digits, `_` and `-`, cannot start with `-`, and must be a single path component. +Empty, missing, duplicate and malformed names are rejected rather than rewritten. + +On this baseline, run the registered native tests with: + +```sh +./SerialPrograms.app/Contents/MacOS/SerialPrograms --command-line-test-mode +# Optional image augmentation: +./SerialPrograms.app/Contents/MacOS/SerialPrograms --command-line-test-mode --augment-color-distortions +``` + +Explicit tests use `QCoreApplication`, bypass settings loading and window +restoration, and never enter startup's serial/camera discovery. macOS test file +output uses `Profiles/unit-tests`; no console profile can be supplied with tests. +The legacy persisted test-mode setting remains supported, but only after a valid +GUI profile is selected. It also runs before device discovery. Prefer the explicit +flag so no saved settings are loaded. + +Unknown or incomplete arguments fail closed with status 2. `--test bdsp` and `--test-filter=...` +are not supported by this baseline. Documented Qt application options (including `-platform offscreen`, `-style Fusion`, +`-style=Fusion`, stylesheet, window and plugin options) are preserved in order and +passed to Qt. Missing values and unknown option spellings are rejected; values in +option/value pairs must not begin with `-`. Qt environment variables such as +`QT_QPA_PLATFORM` remain supported. +The separate `SerialProgramsTests` runner is an independent pending feature; +this lab change does not import it. + +The colocated `StartupArguments_Tests.cpp` table covers the general grammar, +ordinary unprofiled GUI startup, and Qt argument preservation. The separate +`LabStartupPolicy_Tests.cpp` table covers rejection, profile binding, no-argument +lab relaunch and exclusive dispatch to the test entry point. Its injected +GUI callback represents the boundary that owns settings/window/hardware startup. +These tests verify that boundary is not entered; they do not exercise real devices +or claim that all unit-test bodies are incapable of opening hardware. + +Profiles isolate settings, not physical serial devices. A mistakenly configured +profile can still refer to another console's port. Enforcing ownership before a +physical port opens requires a separate device-lease change; the channel owner +and shell lock do not enforce that boundary. + +See [STARTUP_ISOLATION.md](STARTUP_ISOLATION.md) for the review split and upstream path. ## Worked example: run a program with nothing clicked diff --git a/devtools/lab/STARTUP_ISOLATION.md b/devtools/lab/STARTUP_ISOLATION.md new file mode 100644 index 0000000000..a8e986d3d9 --- /dev/null +++ b/devtools/lab/STARTUP_ISOLATION.md @@ -0,0 +1,87 @@ +# Startup isolation: review and upstream path + +A launch intended only to run tests must not restore a saved controller panel. +A lab relaunch must not silently select the live app's default settings. + +The PR #226 lesson at revision `01e6659116f520b51c35ee956aa6a222dfa864f8` +records a `--test bdsp` invocation and profile-free relaunch concerns. That command +is not supported: previously, unrecognized arguments could fall through to GUI +startup. This is a startup problem, independent of AutoStory game logic. + +## Review separately + +1. [PR #234](https://github.com/dayfine/Arduino-Source/pull/234), based on fork + `main`, only extracts service shutdown and worker shutdown from `main()`. + The statements and their order are unchanged, including the Windows Qt + quick-exit branch. It has no lab or gameplay parents and is independently + suitable for an upstream handoff after validation. +2. [PR #233](https://github.com/dayfine/Arduino-Source/pull/233), targeting + `lab/main`, contains the startup behavior change and merges #234's exact + commit without rewriting the previously published history. Its base-relative + diff will still include the mechanical helper extraction until #234 reaches + `lab/main`; review that extraction in #234 rather than as new behavior here. + +To see only behavior changes to Main.cpp after the mechanical prerequisite: + +```sh +git diff origin/startup/shutdown-refactor..origin/lab/startup-isolation -- SerialPrograms/Source/CommonFramework/Main.cpp +``` + +## General mechanism and lab policy + +| Component | Contract | Upstream treatment | +|---|---|---| +| `StartupArguments.h/.cpp` | Pure parser and exclusive GUI/test dispatch; an ordinary no-argument launch remains GUI; documented Qt options are preserved. | Reusable candidate, with its own argument tests. | +| `LabStartupPolicy.h/.cpp` | Require an explicit macOS lab profile or select the compiled identity; reject a conflict. | Keep on lab branches. Never impose this default on normal releases. | +| `Main.cpp` wiring | Parse, apply lab policy, then enter exactly one startup path. Explicit tests skip saved settings, GUI restoration and startup device discovery. | Upstream wiring must omit the lab adapter. | +| `Filesystem::set_startup_profile` | Store an already-validated identity before paths are cached. | Review separately with existing upstream profile behavior and platform support. | +| `PA_LAB_PROFILE` CMake option | Bind the lab binary to one profile even when the OS relaunches it without arguments. | Keep lab-only. | + +The general parser and lab policy have separate native test tables. The lab +regressions also inject entry-point callbacks to verify rejected launches enter +neither path and explicit tests never enter the GUI boundary. macOS CI checks +actual invalid executable invocations. These tests do not exercise hardware or +prove every registered test body is device-free. + +Examples: + +- `SerialPrograms --test bdsp`: reject with status 2 before Qt/settings/devices. +- Ordinary upstream-style parsing with no arguments: select GUI. +- Unbound macOS lab binary with no arguments: lab policy rejects it. +- Binary built with `PA_LAB_PROFILE=lab-B`, relaunched without arguments: GUI + selects `Profiles/lab-B`. +- The same binary with `--profile lab-A`: reject before saved settings load. +- `--command-line-test-mode`: enter the isolated test path, even for a bound lab + build; no console profile may be supplied with the tests. + +## Reuse the pending headless runner upstream + +[PokemonAutomation/Arduino-Source#1845](https://github.com/PokemonAutomation/Arduino-Source/pull/1845) +already provides `SerialProgramsTests` on fork branch `upstream/headless-tests` +(inspected at `006d547f9f5baa2d1e064755b6e45817a6b20aa4`). Its executable owns +QCoreApplication, test selection, logging and shutdown. Do not submit #233's +interim `run_test_application()` as another upstream implementation of that +lifecycle. + +The proposed upstream sequence is: + +1. Review/land the existing headless-runner work and independently review #234's + mechanical extraction. Neither depends on lab policy. +2. Prepare a clean fork draft for general argument validation on those upstream + prerequisites. Preserve no-argument GUI behavior and documented Qt arguments; + run parser regressions on all platforms. Resolve compatibility for the legacy + GUI test-mode flag using the existing runner rather than copying its lifecycle. +3. Keep the lab adapter, compiled profile and lab deployment instructions in + `lab/main`. Consume the accepted general mechanism by merging main as usual. + +No pending headless-runner changes are imported into #233, and this document is +not authorization to publish or modify an upstream PR. The clean upstream +argument-validation follow-up has not been opened yet. + +## Remaining boundary + +Settings isolation cannot stop two different profiles from naming the same +physical serial port. A future device lease must be enforced before a port is +opened, including the first connection/reset. Shell and channel ownership alone +do not protect that boundary. No deployment, permission reset or console run is +part of these PRs.