From b72cd7743880bb454fab9fffa90b07201f1835e8 Mon Sep 17 00:00:00 2001 From: dayfine Date: Sat, 14 Nov 2026 20:52:49 -0800 Subject: [PATCH] Lab: describe_program lists the program's prechecks ProgramInstance gains precheck_summaries(): the program's prechecks in the order it runs them (name, needs, skippable), or nothing when it declares no list. describe_program prints them under "prechecks", or "unsupported" as before. No program declares a list on this branch yet; FRLG RNG's list (fork #485) overrides it once that reaches lab/tooling. --- .../Panels/ProgramDescriptor.h | 18 +++++++++++ .../Source/CommonFramework/ProgramSession.cpp | 6 ++++ .../Source/CommonFramework/ProgramSession.h | 4 +++ .../Source/CommonFramework/Windows/Lab.md | 7 +++- .../CommonFramework/Windows/LabChannel.cpp | 4 ++- .../Windows/LabProgramContract.cpp | 24 ++++++++++++-- .../Windows/LabProgramContract.h | 12 +++++-- .../Windows/LabProgramContract_Tests.cpp | 32 +++++++++++++++++-- 8 files changed, 99 insertions(+), 8 deletions(-) diff --git a/SerialPrograms/Source/CommonFramework/Panels/ProgramDescriptor.h b/SerialPrograms/Source/CommonFramework/Panels/ProgramDescriptor.h index b8dcbc06f1..fc45d225b7 100644 --- a/SerialPrograms/Source/CommonFramework/Panels/ProgramDescriptor.h +++ b/SerialPrograms/Source/CommonFramework/Panels/ProgramDescriptor.h @@ -7,6 +7,9 @@ #ifndef PokemonAutomation_CommonFramework_ProgramDescriptor_H #define PokemonAutomation_CommonFramework_ProgramDescriptor_H +#include +#include +#include #include "Common/Cpp/Options/BatchOption.h" #include "CommonFramework/Notifications/EventNotificationOption.h" #include "PanelDescriptor.h" @@ -30,6 +33,15 @@ enum class AllowCommandsWhenRunning{ ENABLE_COMMANDS, }; +// One check a program runs before it starts, as it is listed without +// running it: its stable name (e.g. "free_party_slots"), one line saying +// what the program needs, and whether the user can turn it off. +struct PrecheckSummary{ + std::string name; + std::string needs; + bool skippable = false; +}; + class ProgramDescriptor : public PanelDescriptor{ @@ -87,6 +99,12 @@ class ProgramInstance{ ProgramEnvironment& env ){} + // The program's prechecks in the order it runs them, or nothing when it + // declares no precheck list. Never touches the console. + virtual std::optional> precheck_summaries() const{ + return std::nullopt; + } + protected: BatchOption m_options; void add_option(ConfigOption& option, std::string serialization_string); diff --git a/SerialPrograms/Source/CommonFramework/ProgramSession.cpp b/SerialPrograms/Source/CommonFramework/ProgramSession.cpp index 344c6648ba..04565b8007 100644 --- a/SerialPrograms/Source/CommonFramework/ProgramSession.cpp +++ b/SerialPrograms/Source/CommonFramework/ProgramSession.cpp @@ -95,6 +95,12 @@ void ProgramSession::join_program_thread() noexcept{ const std::string& ProgramSession::identifier() const{ return m_descriptor.identifier(); } +std::optional> ProgramSession::precheck_summaries() const{ + if (m_instance == nullptr){ + return std::nullopt; + } + return m_instance->precheck_summaries(); +} std::string ProgramSession::current_stats() const{ std::lock_guard lg(m_lock); if (m_current_stats){ diff --git a/SerialPrograms/Source/CommonFramework/ProgramSession.h b/SerialPrograms/Source/CommonFramework/ProgramSession.h index 85f4892054..9cc007fee3 100644 --- a/SerialPrograms/Source/CommonFramework/ProgramSession.h +++ b/SerialPrograms/Source/CommonFramework/ProgramSession.h @@ -79,6 +79,10 @@ class ProgramSession : public TrackableProgram{ uint64_t instance_id() const{ return m_instance_id; } Logger& logger(){ return m_logger; } + // The program's precheck list (ProgramInstance::precheck_summaries()), + // read without running it. Nothing when it declares none. + std::optional> precheck_summaries() const; + // - return struct that contains the list of missing resources and boolean upgrade_warning. // - upgrade_warning: is true if we need to warn the user to upgrade CC. diff --git a/SerialPrograms/Source/CommonFramework/Windows/Lab.md b/SerialPrograms/Source/CommonFramework/Windows/Lab.md index a04edae18d..b62ee7b7ef 100644 --- a/SerialPrograms/Source/CommonFramework/Windows/Lab.md +++ b/SerialPrograms/Source/CommonFramework/Windows/Lab.md @@ -241,7 +241,12 @@ describe_program {"id":"PokemonFRLG:AutoStory","options":[...],"prechecks":"unsu The defaults are the program's defaults, not the values it holds now. Which options show and whether a combination is valid depend on the other options' values; they are not part of the contract. -- `prechecks`: `unsupported` until the program declares a precheck list. +- `prechecks`: the checks the program runs before it starts, in that order, + each `{"name", "needs", "skippable"}`: a stable name (`black_border`, + `free_party_slots`, ...), one line of what the program needs, and whether + the user can turn it off. `unsupported` when the program declares no + precheck list (`ProgramInstance::precheck_summaries()`); that never means + the checks passed. An empty list means the program needs nothing. ## Owner diff --git a/SerialPrograms/Source/CommonFramework/Windows/LabChannel.cpp b/SerialPrograms/Source/CommonFramework/Windows/LabChannel.cpp index eb107d6e5c..ffcf1a7a40 100644 --- a/SerialPrograms/Source/CommonFramework/Windows/LabChannel.cpp +++ b/SerialPrograms/Source/CommonFramework/Windows/LabChannel.cpp @@ -521,7 +521,9 @@ std::string LabChannel::run_describe_program(const std::vector& wor if (options == nullptr){ return "describe_program: the selected program has no options the lab can read."; } - JsonValue contract = lab_program_contract(m_program->descriptor().identifier(), *options); + JsonValue contract = lab_program_contract( + m_program->descriptor().identifier(), *options, m_program->precheck_summaries() + ); out << "describe_program " << contract.dump(-1) << "\n"; return ""; } diff --git a/SerialPrograms/Source/CommonFramework/Windows/LabProgramContract.cpp b/SerialPrograms/Source/CommonFramework/Windows/LabProgramContract.cpp index d732692f82..b63c56e502 100644 --- a/SerialPrograms/Source/CommonFramework/Windows/LabProgramContract.cpp +++ b/SerialPrograms/Source/CommonFramework/Windows/LabProgramContract.cpp @@ -118,6 +118,18 @@ std::optional describe_choice(const ConfigOption& option){ return std::nullopt; } +JsonArray precheck_list(const std::vector& prechecks){ + JsonArray list; + for (const PrecheckSummary& check : prechecks){ + JsonObject item; + item["name"] = check.name; + item["needs"] = check.needs; + item["skippable"] = check.skippable; + list.push_back(std::move(item)); + } + return list; +} + // The fields of `option` for its entry: "type" and those of that type. JsonObject describe_option(const ConfigOption& option){ std::optional described = describe_group(option); @@ -152,12 +164,20 @@ JsonArray lab_option_contract(const BatchOption& options){ return contract; } -JsonObject lab_program_contract(std::string_view id, const BatchOption& options){ +JsonObject lab_program_contract( + std::string_view id, + const BatchOption& options, + const std::optional>& prechecks +){ JsonObject contract; contract["schema"] = LAB_PROGRAM_CONTRACT_SCHEMA; contract["id"] = std::string(id); contract["options"] = lab_option_contract(options); - contract["prechecks"] = "unsupported"; + if (prechecks){ + contract["prechecks"] = precheck_list(*prechecks); + }else{ + contract["prechecks"] = "unsupported"; + } return contract; } diff --git a/SerialPrograms/Source/CommonFramework/Windows/LabProgramContract.h b/SerialPrograms/Source/CommonFramework/Windows/LabProgramContract.h index f2630b7ab3..f03660c868 100644 --- a/SerialPrograms/Source/CommonFramework/Windows/LabProgramContract.h +++ b/SerialPrograms/Source/CommonFramework/Windows/LabProgramContract.h @@ -18,10 +18,13 @@ #ifndef PokemonAutomation_LabProgramContract_H #define PokemonAutomation_LabProgramContract_H +#include #include +#include #include "Common/Cpp/Json/JsonArray.h" #include "Common/Cpp/Json/JsonObject.h" #include "Common/Cpp/Options/BatchOption.h" +#include "CommonFramework/Panels/ProgramDescriptor.h" namespace PokemonAutomation{ @@ -38,8 +41,13 @@ constexpr int LAB_PROGRAM_CONTRACT_SCHEMA = 1; JsonArray lab_option_contract(const BatchOption& options); // The whole reply: {"schema", "id", "options", "prechecks"}. `prechecks` -// is "unsupported" until the program declares a precheck list. -JsonObject lab_program_contract(std::string_view id, const BatchOption& options); +// lists the program's prechecks in order, each {"name", "needs", +// "skippable"}, or is "unsupported" when the program declares no list. +JsonObject lab_program_contract( + std::string_view id, + const BatchOption& options, + const std::optional>& prechecks +); diff --git a/SerialPrograms/Source/CommonFramework/Windows/LabProgramContract_Tests.cpp b/SerialPrograms/Source/CommonFramework/Windows/LabProgramContract_Tests.cpp index ea2582d919..954e63ea0a 100644 --- a/SerialPrograms/Source/CommonFramework/Windows/LabProgramContract_Tests.cpp +++ b/SerialPrograms/Source/CommonFramework/Windows/LabProgramContract_Tests.cpp @@ -5,12 +5,14 @@ * The option contract of "describe_program" for each option type, on a * program's options built here: keys, types, defaults (not the current * values), bounds and enum entries, nested groups, and static options left - * out. + * out; and the program's precheck list, or "unsupported" without one. * */ #include +#include #include +#include #include "Common/Cpp/Json/JsonValue.h" #include "Common/Cpp/Options/BooleanCheckBoxOption.h" #include "Common/Cpp/Options/EnumDropdownOption.h" @@ -173,6 +175,7 @@ const OptionCase OPTION_CASES[] = { struct ProgramInput{ std::string id; + std::optional> prechecks; }; struct ProgramExpectation{ size_t options; // Entries in "options": the static note is left out. @@ -186,7 +189,7 @@ struct ProgramCase{ UnitTestResult check(const ProgramCase& c){ SampleOptions sample; - JsonObject contract = lab_program_contract(c.input.id, sample.options); + JsonObject contract = lab_program_contract(c.input.id, sample.options, c.input.prechecks); const JsonArray* options = contract.get_array(std::string("options")); if (options == nullptr || options->size() != c.expectation.options){ return std::format("expected {} options in\n{}", c.expectation.options, JsonValue(std::move(contract)).dump(-1)); @@ -222,6 +225,31 @@ const ProgramCase PROGRAM_CASES[] = { .head = R"({"id":"PokemonFRLG:AutoStory","options":null,"prechecks":"unsupported","schema":1})", }, }, + { + .name = "a declared precheck list, in order", + .input = { + .id = "PokemonFRLG:GiftRng", + .prechecks = std::vector{ + {.name = "black_border", .needs = "No black border around the game.", .skippable = false}, + {.name = "free_party_slots", .needs = "1 free party slot.", .skippable = true}, + }, + }, + .expectation = { + .options = 8, + .head = R"({"id":"PokemonFRLG:GiftRng","options":null,"prechecks":[{"name":"black_border","needs":"No black border around the game.","skippable":false},{"name":"free_party_slots","needs":"1 free party slot.","skippable":true}],"schema":1})", + }, + }, + { + .name = "an empty list declares no needs, not unsupported", + .input = { + .id = "PokemonFRLG:AutoStory", + .prechecks = std::vector{}, + }, + .expectation = { + .options = 8, + .head = R"({"id":"PokemonFRLG:AutoStory","options":null,"prechecks":[],"schema":1})", + }, + }, };