[codex] Add MetaTrader path discovery helpers

.github/workflows/windows-smoke.yml

@@ -0,0 +1,43 @@
+name: Windows Smoke
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+jobs:
+  metatrader-file:
+    runs-on: windows-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          submodules: recursive
+
+      - name: Configure
+        run: >
+          cmake -S . -B build-windows
+          -DOPTIONX_BUILD_DEPS=ON
+          -DOPTIONX_BUILD_TESTS=ON
+          -DOPTIONX_LIGHTWEIGHT_BRIDGE_SMOKE_TESTS=ON
+
+      - name: Build MetaTrader path discovery test
+        run: cmake --build build-windows --config Debug --target metatrader_paths_test
+
+      - name: Build MetaTrader file transport tests
+        run: >
+          cmake --build build-windows --config Debug --target
+          metatrader_file_config_include_test
+          metatrader_file_bridge_test
+          bridge_umbrella_include_test
+
+      - name: Run MetaTrader file tests
+        shell: pwsh
+        run: |
+          $env:PATH = "$PWD\build-windows\bin;$PWD\build-windows\Debug;$env:PATH"
+          .\build-windows\Debug\metatrader_paths_test.exe --gtest_brief=1
+          .\build-windows\Debug\metatrader_file_config_include_test.exe --gtest_brief=1
+          .\build-windows\Debug\metatrader_file_bridge_test.exe --gtest_brief=1
+          .\build-windows\Debug\bridge_umbrella_include_test.exe --gtest_brief=1

CMakeLists.txt

@@ -3,6 +3,14 @@
 cmake_minimum_required(VERSION 3.18)
 project(optionx_cpp LANGUAGES CXX)
 
+if(MSVC)
+    add_compile_options(/Zc:__cplusplus)
+endif()
+
+if(WIN32)
+    add_compile_definitions(NOMINMAX)
+endif()
+
 set(OPTIONX_TOP_LEVEL OFF)
 if(CMAKE_SOURCE_DIR STREQUAL CMAKE_CURRENT_SOURCE_DIR)
     set(OPTIONX_TOP_LEVEL ON)
@@ -45,6 +53,10 @@ endif()
 option(OPTIONX_BUILD_DEPS "Build bundled optionx dependencies" OFF)
 option(OPTIONX_BUILD_EXAMPLES "Build optionx examples" OFF)
 option(OPTIONX_BUILD_TESTS "Build optionx tests" OFF)
+option(
+    OPTIONX_LIGHTWEIGHT_BRIDGE_SMOKE_TESTS
+    "Link selected bridge smoke tests without the full optionx_cpp dependency graph"
+    OFF)
 set(OPTIONX_DEPS_BUILD_DIR "" CACHE PATH "Path to prebuilt optionx dependencies")
 
 if(OPTIONX_TOP_LEVEL)
@@ -118,6 +130,8 @@ set(OPTIONX_WINDOWS_SYSTEM_LIBS
     ws2_32
     wsock32
     crypt32
+    shell32
+    ole32
     ntdll
     bcrypt
 )
@@ -461,6 +475,17 @@ if(OPTIONX_BUILD_TESTS)
         gtest
     )
 
+    set(OPTIONX_LIGHTWEIGHT_TESTS
+        metatrader_paths_test
+    )
+    if(OPTIONX_LIGHTWEIGHT_BRIDGE_SMOKE_TESTS)
+        list(APPEND OPTIONX_LIGHTWEIGHT_TESTS
+            bridge_umbrella_include_test
+            metatrader_file_bridge_test
+            metatrader_file_config_include_test
+        )
+    endif()
+
     file(GLOB_RECURSE PROJECT_HEADERS
         RELATIVE ${CMAKE_CURRENT_SOURCE_DIR}
         include/*.hpp
@@ -514,6 +539,7 @@ if(OPTIONX_BUILD_TESTS)
         list(APPEND TEST_TARGET_SOURCES "${test_src}")
 
         add_executable(${test_name} ${test_src})
+        target_compile_features(${test_name} PRIVATE cxx_std_17)
 
         target_include_directories(${test_name} PRIVATE
             ${PROJECT_INCLUDE_DIRS}
@@ -526,10 +552,23 @@ if(OPTIONX_BUILD_TESTS)
             ${PROJECT_DEFINES}
             LOGIT_BASE_PATH="${LOGIT_BASE_PATH_FWD}"
         )
-        target_link_libraries(${test_name} PRIVATE ${PROJECT_LIBS} optionx_cpp)
+        list(FIND OPTIONX_LIGHTWEIGHT_TESTS "${test_name}" lightweight_test_index)
+        if(NOT lightweight_test_index EQUAL -1)
+            target_link_libraries(${test_name} PRIVATE ${PROJECT_LIBS})
+            if(WIN32)
+                target_link_libraries(${test_name} PRIVATE ${OPTIONX_WINDOWS_SYSTEM_LIBS})
+            endif()
+        else()
+            target_link_libraries(${test_name} PRIVATE ${PROJECT_LIBS} optionx_cpp)
+        endif()
 
         if(OPTIONX_BUILD_DEPS)
-            foreach(test_dep mdbx-static AES gtest)
+            if(NOT lightweight_test_index EQUAL -1)
+                set(test_deps gtest)
+            else()
+                set(test_deps mdbx-static AES gtest)
+            endif()
+            foreach(test_dep ${test_deps})
                 if(TARGET ${test_dep})
                     add_dependencies(${test_name} ${test_dep})
                 endif()

guides/bridge-protocol-v1/file-transport-and-adapters.md

@@ -69,20 +69,21 @@ file-transport building blocks:
 - `metatrader_file::detail` helpers for path-safe IDs, NDJSON append/read,
   owner-side log cleanup, JSON-RPC request/response/notification documents,
   atomic state snapshots and bounded JSON reads;
+- `utils::metatrader` helpers for resolving the default MetaQuotes roaming
+  location, Common Files root and terminal data directories;
 - small helpers for `balance.updated` and `trade.updated` notification payloads.
 
 This slice does not yet define a long-running `BaseBridge` polling loop, MQL
 advisor code or a broker execution adapter. Those pieces should use these
 helpers in follow-up implementation PRs.
 
-### Future MetaTrader Discovery Utility
+### MetaTrader Discovery Utility
 
-MetaTrader path discovery should be implemented as a reusable utility in a
-follow-up PR, not as ad-hoc logic inside the file bridge. The utility should be
-usable by the file transport, quote translators, MQL sample tooling and future
-MT4/MT5 adapters.
+MetaTrader path discovery is a reusable utility, not ad-hoc logic inside the
+file bridge. The utility is intended for the file transport, quote translators,
+MQL sample tooling and future MT4/MT5 adapters.
 
-Expected responsibilities:
+Responsibilities:
 
 - resolve the default MetaQuotes roaming directory on Windows through the OS
   known-folder API, with `%APPDATA%` only as a fallback;
@@ -97,6 +98,9 @@ Expected responsibilities:
 - keep path confinement and reserved-name checks separate from discovery so the
   bridge can validate configured and discovered roots the same way.
 
+C++ entry points live under `optionx::utils::metatrader` and are exposed through
+`optionx_cpp/utils.hpp` and `optionx_cpp/bridges/metatrader_file.hpp`.
+
 The older `mega-connector` code has useful prior art in
 `tools/mt/common/utils.hpp` (`SHGetKnownFolderPath`, terminal enumeration and
 history-folder discovery), but the OptionX utility should be redesigned around
@@ -287,7 +291,6 @@ append, checkpoint and clear.
 
 Deferred implementation work:
 
-- MetaTrader terminal discovery utilities for locating `Common\Files`.
 - A concrete polling bridge class built on this protocol helper layer.
 - A runtime writer object or owner queue that serializes append, repair and
   owner-side clear operations per log file.

guides/bridge-protocol-v1/file-transport-and-adapters.ru.md

@@ -63,19 +63,21 @@ Reader хранит свой checkpoint и не переписывает append-
 - helpers в `metatrader_file::detail` для path-safe IDs, NDJSON append/read,
   owner-side cleanup, JSON-RPC request/response/notification documents,
   atomic state snapshots и bounded JSON reads;
+- helpers `utils::metatrader` для default MetaQuotes roaming location,
+  Common Files root и terminal data directories;
 - helpers для `balance.updated`, `trade.updated` и `state.json` payloads.
 
 Этот slice еще не задает long-running `BaseBridge` polling loop, MQL advisor
 code или broker execution adapter. Эти части должны использовать helpers в
 следующем implementation PR.
 
-### Future MetaTrader Discovery Utility
+### MetaTrader Discovery Utility
 
-Поиск путей MetaTrader стоит реализовать отдельной reusable utility в будущем
-PR, а не ad-hoc логикой внутри file bridge. Utility должна быть полезна file
-transport, quote translators, MQL sample tooling и будущим MT4/MT5 adapters.
+Поиск путей MetaTrader реализован отдельной reusable utility, а не ad-hoc
+логикой внутри file bridge. Utility предназначена для file transport, quote
+translators, MQL sample tooling и будущих MT4/MT5 adapters.
 
-Expected responsibilities:
+Responsibilities:
 
 - находить default MetaQuotes roaming directory на Windows через OS
   known-folder API, используя `%APPDATA%` только как fallback;
@@ -88,6 +90,9 @@ Expected responsibilities:
 - принимать явно настроенные terminal или Common Files roots без guesswork;
 - держать path confinement и reserved-name checks отдельно от discovery.
 
+C++ entry points находятся в `optionx::utils::metatrader` и доступны через
+`optionx_cpp/utils.hpp` и `optionx_cpp/bridges/metatrader_file.hpp`.
+
 В старом `mega-connector` есть useful prior art в `tools/mt/common/utils.hpp`,
 но OptionX utility лучше спроектировать как набор маленьких testable helpers.
 
@@ -262,7 +267,6 @@ append, checkpoint and clear.
 
 Deferred implementation work:
 
-- MetaTrader terminal discovery utilities for locating `Common\Files`.
 - Concrete polling bridge class built on this protocol helper layer.
 - Runtime writer object or owner queue that serializes append, repair and
   owner-side clear operations per log file.

guides/build-and-test.md

@@ -90,7 +90,7 @@ Target naming:
 - `tradeup_ws_invalid_token_probe` - TradeUp WebSocket probe.
 
 Линкуемые libs для tests в `CMakeLists.txt`: `ws2_32`, `wsock32`, `crypt32`,
-`ssl`, `crypto`, `curl`, `mdbx`, `ntdll`, `bcrypt`, `AES`, `gtest`.
+`ssl`, `crypto`, `curl`, `mdbx`, `shell32`, `ole32`, `ntdll`, `bcrypt`, `AES`, `gtest`.
 
 Compile definition: `ASIO_STANDALONE`. Для tests также задается
 `LOGIT_BASE_PATH`.
@@ -130,6 +130,12 @@ $env:OPTIONX_INTRADE_BAR_CONFIG_FILE="tests\intrade_bar_api\intrade_bar_api.loca
 
 ## Include-Contract Checks
 
+GitHub CI also runs a focused Windows smoke job for MetaTrader file transport
+helpers. It builds and runs `metatrader_paths_test`,
+`metatrader_file_config_include_test`, `metatrader_file_bridge_test` and
+`bridge_umbrella_include_test` on `windows-latest` so Windows filesystem API
+paths such as atomic replacement and exclusive temp creation are covered by CI.
+
 При изменении публичных aggregate headers или include policy добавляй или
 обновляй тест, который подключает intended public entry point:
 

include/optionx_cpp/bridges/metatrader_file.hpp

@@ -6,24 +6,30 @@
 /// \brief Includes MetaTrader file-transport bridge headers.
 
 #include <algorithm>
+#include <atomic>
+#include <cerrno>
 #include <chrono>
 #include <cmath>
 #include <cctype>
 #include <cstdint>
+#include <cstddef>
 #include <cstdlib>
 #include <filesystem>
 #include <fstream>
 #include <iomanip>
+#include <limits>
 #include <locale>
+#include <memory>
 #include <sstream>
 #include <stdexcept>
 #include <string>
 #include <system_error>
 #include <utility>
 #include <vector>
 
-#include "data/bridge.hpp"
-#include "data/trading.hpp"
+#include <optionx_cpp/data/bridge.hpp>
+#include <optionx_cpp/data/trading.hpp>
+#include <optionx_cpp/utils/metatrader_paths.hpp>
 
 #if defined(_WIN32)
 #ifndef NOMINMAX
@@ -33,6 +39,7 @@
 #endif
 
 #include "BaseBridge.hpp"
+#include "metatrader_file/MetaTraderFilePathUtils.hpp"
 #include "metatrader_file/MetaTraderFileBridgeConfig.hpp"
 #include "metatrader_file/detail/MetaTraderFileProtocol.hpp"