From 6308947deb61ee79c1e078d30bb433f2df817e4b Mon Sep 17 00:00:00 2001 From: dayfine Date: Fri, 6 Nov 2026 00:21:17 -0800 Subject: [PATCH 1/7] Fail closed on unsafe lab startup and isolate explicit test launches --- .../workflows/cpp-ci-serial-programs-base.yml | 27 ++- Common/Cpp/Filesystem/Filesystem.h | 9 +- Common/Cpp/Filesystem/Filesystem_Mac.h | 19 +- SerialPrograms/CMakeLists.txt | 9 + .../Source/CommonFramework/Main.cpp | 173 +++++++++++------- .../Startup/StartupArguments.cpp | 83 +++++++++ .../Startup/StartupArguments.h | 52 ++++++ .../Startup/StartupArguments_Tests.cpp | 135 ++++++++++++++ .../Startup/StartupArguments_Tests.h | 15 ++ .../ComputerPrograms_UnitTestRunner.cpp | 2 + SerialPrograms/cmake/SourceFiles.cmake | 4 + devtools/lab/README.md | 64 ++++++- 12 files changed, 501 insertions(+), 91 deletions(-) create mode 100644 SerialPrograms/Source/CommonFramework/Startup/StartupArguments.cpp create mode 100644 SerialPrograms/Source/CommonFramework/Startup/StartupArguments.h create mode 100644 SerialPrograms/Source/CommonFramework/Startup/StartupArguments_Tests.cpp create mode 100644 SerialPrograms/Source/CommonFramework/Startup/StartupArguments_Tests.h 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..b22cb60235 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,7 @@ #include "Logging/Logger.h" #include "Logging/OutputRedirector.h" #include "Startup/SetupSettings.h" +#include "Startup/StartupArguments.h" #include "Startup/NewVersionCheck.h" #include "Windows/MainWindow.h" #include "GlobalSettingsPanel.h" @@ -49,9 +52,9 @@ using namespace PokemonAutomation; namespace PokemonAutomation{ bool use_qt_ui(){ - return true; + return qobject_cast(QCoreApplication::instance()) != nullptr; } -} +} // namespace PokemonAutomation Q_DECLARE_METATYPE(std::string) @@ -90,12 +93,7 @@ FileLogger& global_file_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. @@ -208,34 +206,17 @@ 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); } + 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 +261,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 only services that the GUI startup can initialize. +void stop_application_services(){ #ifdef PA_SOCIAL_SDK Integration::DiscordSocialSDK::DiscordSocial::instance().stop(); #endif @@ -325,6 +285,47 @@ int main(int argc, char *argv[]){ global_watchdog().stop(); global_file_logger().stop(); +} + +// Shared test/GUI worker teardown; no settings, device or GUI services are created. +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 +338,64 @@ 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; +} + +// 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]); + } + StartupPolicy policy; +#if defined(__APPLE__) + policy.profiles = StartupProfiles::REQUIRED; +#ifdef PA_LAB_PROFILE + policy.bound_profile = PA_LAB_PROFILE; +#endif +#endif + const StartupPlan plan = parse_startup_arguments(arguments, policy); + if (plan.mode == StartupMode::REJECTED){ + std::cerr << plan.error << std::endl; + } + // Custom flags have been consumed. Do not let Qt reinterpret them. + int qt_argc = 1; + char* qt_argv[] = {argv[0], nullptr}; + return dispatch_startup(plan, { + .gui = [&](const StartupPlan& selected){ +#if defined(__APPLE__) + Filesystem::set_startup_profile(*selected.profile); +#else + (void)selected; +#endif + return run_gui_application(qt_argc, qt_argv); + }, + .tests = [&](const StartupPlan& selected){ + return run_test_application(qt_argc, qt_argv, selected); + }, + }); +} diff --git a/SerialPrograms/Source/CommonFramework/Startup/StartupArguments.cpp b/SerialPrograms/Source/CommonFramework/Startup/StartupArguments.cpp new file mode 100644 index 0000000000..000312f179 --- /dev/null +++ b/SerialPrograms/Source/CommonFramework/Startup/StartupArguments.cpp @@ -0,0 +1,83 @@ +/* Lab Startup Arguments + * + * From: https://github.com/PokemonAutomation/ + */ +#include +#include "StartupArguments.h" + +namespace PokemonAutomation{ +namespace{ + +// Profile names are single ASCII path components; never silently rewrite an identity. +bool valid_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 == '-'; + }); +} + +// Resolve the selected identity only after all arguments are understood. +StartupPlan resolve_profile(StartupPlan plan, const StartupPolicy& policy){ + if (plan.mode == StartupMode::TESTS){ + if (plan.profile){ + return {.error = "Test launches cannot select a console profile."}; + } + return plan; + } + if (policy.profiles == StartupProfiles::UNSUPPORTED){ + if (plan.profile || policy.bound_profile){ + return {.error = "Settings profiles are supported only on macOS."}; + } + return plan; + } + if (policy.bound_profile){ + if (!valid_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 + +StartupPlan parse_startup_arguments(std::span arguments, const StartupPolicy& policy){ + 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_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{ + return {.error = "Unknown startup argument: " + std::string(arg)}; + } + } + if (plan.augment_color_distortions && plan.mode != StartupMode::TESTS){ + return {.error = "--augment-color-distortions requires --command-line-test-mode."}; + } + return resolve_profile(std::move(plan), policy); +} + +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..6990849ca5 --- /dev/null +++ b/SerialPrograms/Source/CommonFramework/Startup/StartupArguments.h @@ -0,0 +1,52 @@ +/* Lab 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 + +namespace PokemonAutomation{ + +// Whether this platform supports isolated macOS settings profiles. +enum class StartupProfiles{UNSUPPORTED, REQUIRED}; + +// A build-bound profile survives Finder and permission-dialog relaunches. +struct StartupPolicy{ + StartupProfiles profiles = StartupProfiles::UNSUPPORTED; + std::optional bound_profile = std::nullopt; +}; + +// 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 = {}; +}; + +// Parse arguments excluding argv[0]. Unknown, ambiguous and unsafe inputs fail closed. +StartupPlan parse_startup_arguments(std::span arguments, const StartupPolicy& policy); + +// 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..06128b8d40 --- /dev/null +++ b/SerialPrograms/Source/CommonFramework/Startup/StartupArguments_Tests.cpp @@ -0,0 +1,135 @@ +/* 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 "StartupArguments.h" +#include "StartupArguments_Tests.h" + +namespace PokemonAutomation{ +namespace{ + +struct StartupInput{ + std::string_view name; + std::vector arguments; + StartupPolicy policy; +}; + +struct StartupExpectation{ + StartupMode mode; + std::optional profile = std::nullopt; + bool augment = false; + int gui_calls = 0; + int test_calls = 0; + int exit_code = 2; +}; + +struct StartupCase{ + StartupInput input; + StartupExpectation expectation; +}; + +const StartupCase STARTUP_CASES[] = { + {.input = {.name = "unbound relaunch", .arguments = {}, .policy = {StartupProfiles::REQUIRED}}, + .expectation = {.mode = StartupMode::REJECTED}}, + {.input = {.name = "bound relaunch", .arguments = {}, .policy = {StartupProfiles::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 = {StartupProfiles::REQUIRED}}, + .expectation = {.mode = StartupMode::GUI, .profile = "lab-B", .gui_calls = 1, .exit_code = 17}}, + {.input = {.name = "matching identity", .arguments = {"--profile", "lab-B"}, .policy = {StartupProfiles::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 = {StartupProfiles::REQUIRED, "lab-B"}}, + .expectation = {.mode = StartupMode::REJECTED}}, + {.input = {.name = "missing profile", .arguments = {"--profile"}, .policy = {StartupProfiles::REQUIRED}}, + .expectation = {.mode = StartupMode::REJECTED}}, + {.input = {.name = "empty profile", .arguments = {"--profile", ""}, .policy = {StartupProfiles::REQUIRED}}, + .expectation = {.mode = StartupMode::REJECTED}}, + {.input = {.name = "duplicate profile", .arguments = {"--profile", "lab-B", "--profile", "lab-B"}, .policy = {StartupProfiles::REQUIRED}}, + .expectation = {.mode = StartupMode::REJECTED}}, + {.input = {.name = "path traversal", .arguments = {"--profile", "../lab-A"}, .policy = {StartupProfiles::REQUIRED}}, + .expectation = {.mode = StartupMode::REJECTED}}, + {.input = {.name = "absolute profile", .arguments = {"--profile", "/lab-A"}, .policy = {StartupProfiles::REQUIRED}}, + .expectation = {.mode = StartupMode::REJECTED}}, + {.input = {.name = "space in profile", .arguments = {"--profile", "lab B"}, .policy = {StartupProfiles::REQUIRED}}, + .expectation = {.mode = StartupMode::REJECTED}}, + {.input = {.name = "unicode profile", .arguments = {"--profile", "lab-é"}, .policy = {StartupProfiles::REQUIRED}}, + .expectation = {.mode = StartupMode::REJECTED}}, + {.input = {.name = "option as profile", .arguments = {"--profile", "--command-line-test-mode"}, .policy = {StartupProfiles::REQUIRED}}, + .expectation = {.mode = StartupMode::REJECTED}}, + {.input = {.name = "test typo from incident", .arguments = {"--test", "bdsp"}, .policy = {StartupProfiles::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 = {StartupProfiles::REQUIRED}}, + .expectation = {.mode = StartupMode::TESTS, .test_calls = 1, .exit_code = 23}}, + {.input = {.name = "test bypasses bound console", .arguments = {"--command-line-test-mode"}, .policy = {StartupProfiles::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 = {StartupProfiles::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 = {StartupProfiles::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_startup_case(const StartupCase& test){ + const StartupPlan plan = parse_startup_arguments(test.input.arguments, test.input.policy); + const StartupExpectation& 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.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 StartupTest : public UnitTest{ +public: + explicit StartupTest(const StartupCase& test) + : UnitTest("Startup/" + std::string(test.input.name)) + , m_test(test) + {} + virtual UnitTestResult run(Logger&, CancellableScope&) const override{ + return check_startup_case(m_test); + } +private: + const StartupCase& m_test; +}; + +} // namespace + +void add_tests_StartupArguments(UnitTestDatabase& database){ + for (const StartupCase& test : STARTUP_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..c055a0b42d 100644 --- a/SerialPrograms/Source/ComputerPrograms/ComputerPrograms_UnitTestRunner.cpp +++ b/SerialPrograms/Source/ComputerPrograms/ComputerPrograms_UnitTestRunner.cpp @@ -22,6 +22,7 @@ #include "CommonFramework/ProgramStats/StatsTracking.h" #include "CommonFramework/Tools/GlobalThreadPools.h" #include "CommonFramework/Windows/LabChannel_Tests.h" +#include "CommonFramework/Startup/StartupArguments_Tests.h" #include "CommonTools/VisualDetectors/BlackBorderDetector.h" #include "CommonTools/OCR/OCR_Tests.h" @@ -63,6 +64,7 @@ UnitTestDatabase make_UNIT_TESTS_ALL(){ add_tests_SinkPipeline(ret); add_tests_AudioFileLoader(ret); add_tests_LabChannel(ret); + add_tests_StartupArguments(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..226174c170 100644 --- a/SerialPrograms/cmake/SourceFiles.cmake +++ b/SerialPrograms/cmake/SourceFiles.cmake @@ -717,6 +717,10 @@ file(GLOB LIBRARY_SOURCES Source/CommonFramework/Startup/NewVersionCheck.h Source/CommonFramework/Startup/SetupSettings.cpp Source/CommonFramework/Startup/SetupSettings.h + SerialPrograms/Source/CommonFramework/Startup/StartupArguments.cpp + SerialPrograms/Source/CommonFramework/Startup/StartupArguments.h + SerialPrograms/Source/CommonFramework/Startup/StartupArguments_Tests.cpp + SerialPrograms/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..0a44365882 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,61 @@ 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 arguments fail closed with status 2. `--test bdsp` and `--test-filter=...` +are not supported by this baseline. Arbitrary Qt command-line flags are also +rejected; use Qt environment variables such as `QT_QPA_PLATFORM` where needed. +The separate `SerialProgramsTests` runner is an independent pending feature; +this lab change does not import it. + +The colocated `StartupArguments_Tests.cpp` table covers rejection, profile binding, +no-argument 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. ## Worked example: run a program with nothing clicked From 7d0d1cc7a59fba1eeca58a3140191db5c3afb2c1 Mon Sep 17 00:00:00 2001 From: dayfine Date: Fri, 6 Nov 2026 00:30:31 -0800 Subject: [PATCH 2/7] Fix startup source paths in the application build --- SerialPrograms/cmake/SourceFiles.cmake | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/SerialPrograms/cmake/SourceFiles.cmake b/SerialPrograms/cmake/SourceFiles.cmake index 226174c170..4b75cdb45d 100644 --- a/SerialPrograms/cmake/SourceFiles.cmake +++ b/SerialPrograms/cmake/SourceFiles.cmake @@ -717,10 +717,10 @@ file(GLOB LIBRARY_SOURCES Source/CommonFramework/Startup/NewVersionCheck.h Source/CommonFramework/Startup/SetupSettings.cpp Source/CommonFramework/Startup/SetupSettings.h - SerialPrograms/Source/CommonFramework/Startup/StartupArguments.cpp - SerialPrograms/Source/CommonFramework/Startup/StartupArguments.h - SerialPrograms/Source/CommonFramework/Startup/StartupArguments_Tests.cpp - SerialPrograms/Source/CommonFramework/Startup/StartupArguments_Tests.h + Source/CommonFramework/Startup/StartupArguments.cpp + Source/CommonFramework/Startup/StartupArguments.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 From faf24e91ae6c277ee6f8cee6ae8bd77c9db99a87 Mon Sep 17 00:00:00 2001 From: dayfine Date: Fri, 6 Nov 2026 00:31:15 -0800 Subject: [PATCH 3/7] Extract application shutdown without changing startup behavior --- .../Source/CommonFramework/Main.cpp | 78 +++++++++++-------- 1 file changed, 47 insertions(+), 31 deletions(-) diff --git a/SerialPrograms/Source/CommonFramework/Main.cpp b/SerialPrograms/Source/CommonFramework/Main.cpp index 0e7bb7fd3f..2e29324bc5 100644 --- a/SerialPrograms/Source/CommonFramework/Main.cpp +++ b/SerialPrograms/Source/CommonFramework/Main.cpp @@ -280,6 +280,51 @@ int run_program(int argc, char *argv[]){ } +namespace{ + +// 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 + +#ifdef PA_DPP + Integration::DppClient::Client::instance().stop(); +#endif + + // We must clear the OCR cache or it will crash on Linux when the library + // unloads before the cache is destructed from static memory. + OCR::clear_ocr_cache(); + + // Stop the controllers. + global_input_stop(); + + // Stop misc. services. + Integration::DiscordWebhook::DiscordWebhookSender::instance().stop(); + SystemSleepController::instance().stop(); + global_periodic_runner().stop(); + 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(); + +} + +} // namespace + int main(int argc, char *argv[]){ #if 0 // Retrieve and store program name @@ -303,27 +348,7 @@ int main(int argc, char *argv[]){ int ret = run_program(argc, argv); -#ifdef PA_SOCIAL_SDK - Integration::DiscordSocialSDK::DiscordSocial::instance().stop(); -#endif - -#ifdef PA_DPP - Integration::DppClient::Client::instance().stop(); -#endif - - // We must clear the OCR cache or it will crash on Linux when the library - // unloads before the cache is destructed from static memory. - OCR::clear_ocr_cache(); - - // Stop the controllers. - global_input_stop(); - - // Stop misc. services. - Integration::DiscordWebhook::DiscordWebhookSender::instance().stop(); - SystemSleepController::instance().stop(); - global_periodic_runner().stop(); - global_watchdog().stop(); - global_file_logger().stop(); + stop_application_services(); // // Workaround Qt 6.9 thread-adoption bug on Windows. @@ -337,16 +362,7 @@ 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; From 87d48d14dbfa34e17903ef64feb6706865e175d6 Mon Sep 17 00:00:00 2001 From: dayfine Date: Fri, 6 Nov 2026 00:36:07 -0800 Subject: [PATCH 4/7] Separate general startup validation from lab identity policy --- .../Source/CommonFramework/Main.cpp | 23 ++- .../Startup/LabStartupPolicy.cpp | 32 ++++ .../Startup/LabStartupPolicy.h | 25 +++ .../Startup/LabStartupPolicy_Tests.cpp | 139 +++++++++++++++++ .../Startup/LabStartupPolicy_Tests.h | 15 ++ .../Startup/StartupArguments.cpp | 68 ++++---- .../Startup/StartupArguments.h | 19 +-- .../Startup/StartupArguments_Tests.cpp | 147 +++++++----------- .../ComputerPrograms_UnitTestRunner.cpp | 2 + SerialPrograms/cmake/SourceFiles.cmake | 4 + devtools/lab/README.md | 17 +- devtools/lab/STARTUP_ISOLATION.md | 87 +++++++++++ 12 files changed, 435 insertions(+), 143 deletions(-) create mode 100644 SerialPrograms/Source/CommonFramework/Startup/LabStartupPolicy.cpp create mode 100644 SerialPrograms/Source/CommonFramework/Startup/LabStartupPolicy.h create mode 100644 SerialPrograms/Source/CommonFramework/Startup/LabStartupPolicy_Tests.cpp create mode 100644 SerialPrograms/Source/CommonFramework/Startup/LabStartupPolicy_Tests.h create mode 100644 devtools/lab/STARTUP_ISOLATION.md diff --git a/SerialPrograms/Source/CommonFramework/Main.cpp b/SerialPrograms/Source/CommonFramework/Main.cpp index 109a3957e9..de39860da0 100644 --- a/SerialPrograms/Source/CommonFramework/Main.cpp +++ b/SerialPrograms/Source/CommonFramework/Main.cpp @@ -41,6 +41,7 @@ #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" @@ -375,20 +376,26 @@ int main(int argc, char* argv[]){ for (int i = 1; i < argc; i++){ arguments.emplace_back(argv[i]); } - StartupPolicy policy; + LabStartupPolicy policy; #if defined(__APPLE__) - policy.profiles = StartupProfiles::REQUIRED; + policy.profiles = LabProfileMode::REQUIRED; #ifdef PA_LAB_PROFILE policy.bound_profile = PA_LAB_PROFILE; #endif #endif - const StartupPlan plan = parse_startup_arguments(arguments, policy); + const StartupPlan plan = apply_lab_startup_policy(parse_startup_arguments(arguments), policy); if (plan.mode == StartupMode::REJECTED){ std::cerr << plan.error << std::endl; } - // Custom flags have been consumed. Do not let Qt reinterpret them. - int qt_argc = 1; - char* qt_argv[] = {argv[0], nullptr}; + // 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 dispatch_startup(plan, { .gui = [&](const StartupPlan& selected){ #if defined(__APPLE__) @@ -396,10 +403,10 @@ int main(int argc, char* argv[]){ #else (void)selected; #endif - return run_gui_application(qt_argc, qt_argv); + return run_gui_application(qt_argc, qt_argv.data()); }, .tests = [&](const StartupPlan& selected){ - return run_test_application(qt_argc, qt_argv, selected); + return 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 index 000312f179..fbe2ea3952 100644 --- a/SerialPrograms/Source/CommonFramework/Startup/StartupArguments.cpp +++ b/SerialPrograms/Source/CommonFramework/Startup/StartupArguments.cpp @@ -6,51 +6,59 @@ #include "StartupArguments.h" namespace PokemonAutomation{ -namespace{ - // Profile names are single ASCII path components; never silently rewrite an identity. -bool valid_profile(std::string_view profile){ +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 == '-'; }); } -// Resolve the selected identity only after all arguments are understood. -StartupPlan resolve_profile(StartupPlan plan, const StartupPolicy& policy){ - if (plan.mode == StartupMode::TESTS){ - if (plan.profile){ - return {.error = "Test launches cannot select a console profile."}; - } - return plan; +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; } - if (policy.profiles == StartupProfiles::UNSUPPORTED){ - if (plan.profile || policy.bound_profile){ - return {.error = "Settings profiles are supported only on macOS."}; + 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; } - return plan; + plan.qt_arguments.emplace_back(arg); + plan.qt_arguments.emplace_back(arguments[++index]); + return QtArgument::ACCEPTED; } - if (policy.bound_profile){ - if (!valid_profile(*policy.bound_profile) || - (plan.profile && plan.profile != policy.bound_profile)){ - return {.error = "The requested profile does not match this lab build."}; + 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; } - 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; + return QtArgument::UNKNOWN; } } // namespace -StartupPlan parse_startup_arguments(std::span arguments, const StartupPolicy& policy){ +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_profile(arguments[i + 1])){ + 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]; @@ -59,13 +67,19 @@ StartupPlan parse_startup_arguments(std::span arguments, }else if (arg == "--augment-color-distortions"){ plan.augment_color_distortions = true; }else{ - return {.error = "Unknown startup argument: " + std::string(arg)}; + 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."}; } - return resolve_profile(std::move(plan), policy); + 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){ diff --git a/SerialPrograms/Source/CommonFramework/Startup/StartupArguments.h b/SerialPrograms/Source/CommonFramework/Startup/StartupArguments.h index 6990849ca5..5a032ae61d 100644 --- a/SerialPrograms/Source/CommonFramework/Startup/StartupArguments.h +++ b/SerialPrograms/Source/CommonFramework/Startup/StartupArguments.h @@ -13,18 +13,10 @@ #include #include #include +#include namespace PokemonAutomation{ -// Whether this platform supports isolated macOS settings profiles. -enum class StartupProfiles{UNSUPPORTED, REQUIRED}; - -// A build-bound profile survives Finder and permission-dialog relaunches. -struct StartupPolicy{ - StartupProfiles profiles = StartupProfiles::UNSUPPORTED; - std::optional bound_profile = std::nullopt; -}; - // Rejected launches must not enter either application entry point. enum class StartupMode{REJECTED, GUI, TESTS}; @@ -34,10 +26,15 @@ struct StartupPlan{ std::optional profile = std::nullopt; bool augment_color_distortions = false; std::string error = {}; + std::vector qt_arguments = {}; }; -// Parse arguments excluding argv[0]. Unknown, ambiguous and unsafe inputs fail closed. -StartupPlan parse_startup_arguments(std::span arguments, const StartupPolicy& policy); +// 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{ diff --git a/SerialPrograms/Source/CommonFramework/Startup/StartupArguments_Tests.cpp b/SerialPrograms/Source/CommonFramework/Startup/StartupArguments_Tests.cpp index 06128b8d40..bae0d6f3fc 100644 --- a/SerialPrograms/Source/CommonFramework/Startup/StartupArguments_Tests.cpp +++ b/SerialPrograms/Source/CommonFramework/Startup/StartupArguments_Tests.cpp @@ -1,134 +1,97 @@ -/* Lab Startup Tests +/* Application Startup Argument 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 "StartupArguments.h" #include "StartupArguments_Tests.h" namespace PokemonAutomation{ namespace{ -struct StartupInput{ +struct ArgumentInput{ std::string_view name; std::vector arguments; - StartupPolicy policy; }; -struct StartupExpectation{ +struct ArgumentExpectation{ 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 StartupCase{ - StartupInput input; - StartupExpectation expectation; +struct ArgumentCase{ + ArgumentInput input; + ArgumentExpectation expectation; }; -const StartupCase STARTUP_CASES[] = { - {.input = {.name = "unbound relaunch", .arguments = {}, .policy = {StartupProfiles::REQUIRED}}, - .expectation = {.mode = StartupMode::REJECTED}}, - {.input = {.name = "bound relaunch", .arguments = {}, .policy = {StartupProfiles::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 = {StartupProfiles::REQUIRED}}, - .expectation = {.mode = StartupMode::GUI, .profile = "lab-B", .gui_calls = 1, .exit_code = 17}}, - {.input = {.name = "matching identity", .arguments = {"--profile", "lab-B"}, .policy = {StartupProfiles::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 = {StartupProfiles::REQUIRED, "lab-B"}}, - .expectation = {.mode = StartupMode::REJECTED}}, - {.input = {.name = "missing profile", .arguments = {"--profile"}, .policy = {StartupProfiles::REQUIRED}}, - .expectation = {.mode = StartupMode::REJECTED}}, - {.input = {.name = "empty profile", .arguments = {"--profile", ""}, .policy = {StartupProfiles::REQUIRED}}, - .expectation = {.mode = StartupMode::REJECTED}}, - {.input = {.name = "duplicate profile", .arguments = {"--profile", "lab-B", "--profile", "lab-B"}, .policy = {StartupProfiles::REQUIRED}}, - .expectation = {.mode = StartupMode::REJECTED}}, - {.input = {.name = "path traversal", .arguments = {"--profile", "../lab-A"}, .policy = {StartupProfiles::REQUIRED}}, - .expectation = {.mode = StartupMode::REJECTED}}, - {.input = {.name = "absolute profile", .arguments = {"--profile", "/lab-A"}, .policy = {StartupProfiles::REQUIRED}}, - .expectation = {.mode = StartupMode::REJECTED}}, - {.input = {.name = "space in profile", .arguments = {"--profile", "lab B"}, .policy = {StartupProfiles::REQUIRED}}, - .expectation = {.mode = StartupMode::REJECTED}}, - {.input = {.name = "unicode profile", .arguments = {"--profile", "lab-é"}, .policy = {StartupProfiles::REQUIRED}}, - .expectation = {.mode = StartupMode::REJECTED}}, - {.input = {.name = "option as profile", .arguments = {"--profile", "--command-line-test-mode"}, .policy = {StartupProfiles::REQUIRED}}, - .expectation = {.mode = StartupMode::REJECTED}}, - {.input = {.name = "test typo from incident", .arguments = {"--test", "bdsp"}, .policy = {StartupProfiles::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 = {StartupProfiles::REQUIRED}}, - .expectation = {.mode = StartupMode::TESTS, .test_calls = 1, .exit_code = 23}}, - {.input = {.name = "test bypasses bound console", .arguments = {"--command-line-test-mode"}, .policy = {StartupProfiles::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 = {StartupProfiles::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 = {StartupProfiles::REQUIRED, "../lab-A"}}, +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}}, }; -// 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_startup_case(const StartupCase& test){ - const StartupPlan plan = parse_startup_arguments(test.input.arguments, test.input.policy); - const StartupExpectation& 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.mode == StartupMode::REJECTED) != !plan.error.empty()){ - return "Expected rejection reason exactly when startup is 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("")); } - 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); + if (plan.qt_arguments != expected.qt_arguments){ + return "Expected the complete Qt argument sequence to be preserved in order."; } return true; } -class StartupTest : public UnitTest{ +class ArgumentTest : public UnitTest{ public: - explicit StartupTest(const StartupCase& test) - : UnitTest("Startup/" + std::string(test.input.name)) + 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_startup_case(m_test); + return check_argument_case(m_test); } private: - const StartupCase& m_test; + const ArgumentCase& m_test; }; } // namespace void add_tests_StartupArguments(UnitTestDatabase& database){ - for (const StartupCase& test : STARTUP_CASES){ - database.add(test); + for (const ArgumentCase& test : ARGUMENT_CASES){ + database.add(test); } } diff --git a/SerialPrograms/Source/ComputerPrograms/ComputerPrograms_UnitTestRunner.cpp b/SerialPrograms/Source/ComputerPrograms/ComputerPrograms_UnitTestRunner.cpp index c055a0b42d..c31934af2e 100644 --- a/SerialPrograms/Source/ComputerPrograms/ComputerPrograms_UnitTestRunner.cpp +++ b/SerialPrograms/Source/ComputerPrograms/ComputerPrograms_UnitTestRunner.cpp @@ -23,6 +23,7 @@ #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" @@ -65,6 +66,7 @@ UnitTestDatabase make_UNIT_TESTS_ALL(){ 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 4b75cdb45d..7b51d92e21 100644 --- a/SerialPrograms/cmake/SourceFiles.cmake +++ b/SerialPrograms/cmake/SourceFiles.cmake @@ -719,6 +719,10 @@ file(GLOB LIBRARY_SOURCES 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 diff --git a/devtools/lab/README.md b/devtools/lab/README.md index 0a44365882..8dc1560664 100644 --- a/devtools/lab/README.md +++ b/devtools/lab/README.md @@ -111,14 +111,19 @@ 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 arguments fail closed with status 2. `--test bdsp` and `--test-filter=...` -are not supported by this baseline. Arbitrary Qt command-line flags are also -rejected; use Qt environment variables such as `QT_QPA_PLATFORM` where needed. +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 rejection, profile binding, -no-argument relaunch and exclusive dispatch to the test entry point. Its injected +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. @@ -128,6 +133,8 @@ 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 ```sh 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. From 5a8e7b44aa101db55d0ab7032908b24ea63cc9a4 Mon Sep 17 00:00:00 2001 From: dayfine Date: Fri, 6 Nov 2026 00:36:52 -0800 Subject: [PATCH 5/7] Keep device shutdown initialization out of persisted test mode --- SerialPrograms/Source/CommonFramework/Main.cpp | 10 +++++----- .../CommonFramework/Startup/StartupArguments.cpp | 2 +- .../Source/CommonFramework/Startup/StartupArguments.h | 2 +- 3 files changed, 7 insertions(+), 7 deletions(-) diff --git a/SerialPrograms/Source/CommonFramework/Main.cpp b/SerialPrograms/Source/CommonFramework/Main.cpp index de39860da0..de46784715 100644 --- a/SerialPrograms/Source/CommonFramework/Main.cpp +++ b/SerialPrograms/Source/CommonFramework/Main.cpp @@ -187,11 +187,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)){ @@ -214,6 +209,11 @@ int run_program(int argc, char *argv[]){ 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(); diff --git a/SerialPrograms/Source/CommonFramework/Startup/StartupArguments.cpp b/SerialPrograms/Source/CommonFramework/Startup/StartupArguments.cpp index fbe2ea3952..e272e05991 100644 --- a/SerialPrograms/Source/CommonFramework/Startup/StartupArguments.cpp +++ b/SerialPrograms/Source/CommonFramework/Startup/StartupArguments.cpp @@ -1,4 +1,4 @@ -/* Lab Startup Arguments +/* Application Startup Arguments * * From: https://github.com/PokemonAutomation/ */ diff --git a/SerialPrograms/Source/CommonFramework/Startup/StartupArguments.h b/SerialPrograms/Source/CommonFramework/Startup/StartupArguments.h index 5a032ae61d..895b4345d3 100644 --- a/SerialPrograms/Source/CommonFramework/Startup/StartupArguments.h +++ b/SerialPrograms/Source/CommonFramework/Startup/StartupArguments.h @@ -1,4 +1,4 @@ -/* Lab Startup Arguments +/* Application Startup Arguments * * From: https://github.com/PokemonAutomation/ * From ccb626f1f0ef4e0d1bb039494efdd93268d970f0 Mon Sep 17 00:00:00 2001 From: dayfine Date: Fri, 6 Nov 2026 00:40:26 -0800 Subject: [PATCH 6/7] Group Main.cpp helpers in one anonymous namespace --- SerialPrograms/Source/CommonFramework/Main.cpp | 18 ++++++------------ 1 file changed, 6 insertions(+), 12 deletions(-) diff --git a/SerialPrograms/Source/CommonFramework/Main.cpp b/SerialPrograms/Source/CommonFramework/Main.cpp index 2e29324bc5..3522fdb665 100644 --- a/SerialPrograms/Source/CommonFramework/Main.cpp +++ b/SerialPrograms/Source/CommonFramework/Main.cpp @@ -45,15 +45,17 @@ #include "PersistentSettings.h" #include "NintendoSwitch/NintendoSwitch_SettingsPanel.h" +Q_DECLARE_METATYPE(std::string) + using namespace PokemonAutomation; namespace PokemonAutomation{ - bool use_qt_ui(){ - return true; - } +bool use_qt_ui(){ + return true; } +} // namespace PokemonAutomation -Q_DECLARE_METATYPE(std::string) +namespace{ void set_working_directory(){ const std::string app_dir = Filesystem::application_binary_directory().string_slash_normalized(); @@ -69,10 +71,6 @@ void set_working_directory(){ } } -namespace PokemonAutomation{ - - - FileLogger& global_file_logger(){ static FileLogger logger( GlobalThreadPools::unlimited_normal(), @@ -83,8 +81,6 @@ FileLogger& global_file_logger(){ return logger; } -} - int run_program(int argc, char *argv[]){ @@ -280,8 +276,6 @@ int run_program(int argc, char *argv[]){ } -namespace{ - // Stop GUI services after run_program() returns, preserving the existing order. void stop_application_services(){ #ifdef PA_SOCIAL_SDK From a380f2cb34b5e59937d36730d482334b88bd786a Mon Sep 17 00:00:00 2001 From: dayfine Date: Fri, 6 Nov 2026 00:47:15 -0800 Subject: [PATCH 7/7] Nest file-local helpers in PokemonAutomation without a using directive --- SerialPrograms/Source/CommonFramework/Main.cpp | 12 +++++------- 1 file changed, 5 insertions(+), 7 deletions(-) diff --git a/SerialPrograms/Source/CommonFramework/Main.cpp b/SerialPrograms/Source/CommonFramework/Main.cpp index 3522fdb665..50018b7585 100644 --- a/SerialPrograms/Source/CommonFramework/Main.cpp +++ b/SerialPrograms/Source/CommonFramework/Main.cpp @@ -47,13 +47,10 @@ Q_DECLARE_METATYPE(std::string) -using namespace PokemonAutomation; - namespace PokemonAutomation{ bool use_qt_ui(){ return true; } -} // namespace PokemonAutomation namespace{ @@ -318,6 +315,7 @@ void stop_thread_pools(){ } } // namespace +} // namespace PokemonAutomation int main(int argc, char *argv[]){ #if 0 @@ -337,12 +335,12 @@ int main(int argc, char *argv[]){ // So far, this is only needed on Mac where static initialization is fucked up. PokemonAutomation::register_all_statics(); - setup_crash_handler(); + PokemonAutomation::setup_crash_handler(); - int ret = run_program(argc, argv); + int ret = PokemonAutomation::run_program(argc, argv); - stop_application_services(); + PokemonAutomation::stop_application_services(); // // Workaround Qt 6.9 thread-adoption bug on Windows. @@ -356,7 +354,7 @@ int main(int argc, char *argv[]){ std::quick_exit(ret); #endif - stop_thread_pools(); + PokemonAutomation::stop_thread_pools(); std::cout << "Exiting main()..." << std::endl;