From f5493e0868630a71486b32ecf50348153f4d3035 Mon Sep 17 00:00:00 2001 From: vczh Date: Tue, 4 Aug 2026 02:05:21 -0700 Subject: [PATCH] Sync copilot context --- .github/Guidelines/Coding.md | 12 ++++++++++++ ..._Design_RemoteProtocolRendererAndSerialization.md | 4 ++-- .github/KnowledgeBase/Learning.md | 8 ++++---- .../manual/gacui/coding-agent/automation-service.md | 4 ++-- 4 files changed, 20 insertions(+), 8 deletions(-) diff --git a/.github/Guidelines/Coding.md b/.github/Guidelines/Coding.md index a477bba0..0603e591 100644 --- a/.github/Guidelines/Coding.md +++ b/.github/Guidelines/Coding.md @@ -13,6 +13,18 @@ In general, here is my preference for any languages: - DRY requires finding if a feature has already been implemented somewhere else before implementing it. avoiding massive duplication. - If the existing implementation is not sharable, refactoring is preferred. - Unless explicitly instructed, do not invent your own code generator as part of the committed solution. It adds more technical debt in maintenance. +- When it is not explicltly instructed, be conservative on creating new layers of abstractions: + - It should bring actual benefits, including better separation of ownership and dependencies, allowing needed extensibility. + - Extraction of common code would also be a good reason, when it doesn't fragmentize the code. I am not a fan of big amounts of small functions. + - Extractin of functions/classes are welcome, when there are large pieces of duplicated code, or when the same logic is duplicated >= 3 times. + - Extraction of common interfaces (aka abstract classes in C++) are welcome, when the details of implementation does not really affect how algorithms and tools are built around the concept. +- Unless explicitly instructed: + - Prefer static analyzing (including ultilizing the type system, or static assertions, etc) over dynamic/runtime assertion. + - Prefer correctness over stability. + - Prefer crashing early over recovery. + - Crashing expose issues immediately, if something can be fixed and made correctly, there is no need to care about what to do when it fails unexpectedly. + - Expected failures should be part of the signature, when the type system cannot represents expected failures, comments are needed. + - Handle exceptions only when recovery is practical. DO NOT consume exceptions silently. ## Be Brave Enough to Fix Upstream Code and Make Breaking Change diff --git a/.github/KnowledgeBase/KB_GacUI_Design_RemoteProtocolRendererAndSerialization.md b/.github/KnowledgeBase/KB_GacUI_Design_RemoteProtocolRendererAndSerialization.md index 9d1d15cb..be682eaf 100644 --- a/.github/KnowledgeBase/KB_GacUI_Design_RemoteProtocolRendererAndSerialization.md +++ b/.github/KnowledgeBase/KB_GacUI_Design_RemoteProtocolRendererAndSerialization.md @@ -142,14 +142,14 @@ Located at `Test/GacUISrc/RemotingTest_Core/`. Accepts `/Pipe` or `/Http` argume Located at `Test/GacUISrc/RemotingTest_Rendering_Win32/`. Accepts `/Pipe` or `/Http` arguments to start as a named-pipe or HTTP client. **Protocol stack setup** (`StartClient` in `GuiMain.cpp`; this function is not a template): -1. Receives a named-pipe, Windows HTTP, or MiniHTTP `INetworkProtocolClient` and creates the shared `RemotingChannelClient`, derived from `GuiRemoteProtocolChannelClient`, over it. +1. Receives a named-pipe, Windows HTTP, or MiniHTTP `INetworkProtocolClient` and creates the shared `RemoteProtocolRendererClient`, derived from `GuiRemoteProtocolChannelClient`, over it. 2. Creates `GuiRemoteProtocolAsyncJsonChannelRenderer` over the client's protocol channel. 3. Creates `GuiRemoteRendererSingle` and `GuiRemoteProtocolRendererChannel(&asyncRendererChannel, &remoteRenderer)`. 4. Waits for the server, then calls `SetupRawWindowsDirect2DRenderer()` to run the native window event loop. 5. In `GuiMain()`, creates the native window, registers it with `GuiRemoteRendererSingle`, creates a retained `Ptr`, installs it through `asyncChannel->SetInvokeInMainThread(invoker)`, drains startup work with `ProcessPendingMessages()`, and runs the window service. 6. On exit, clears the invoker, unregisters the main window, stops the network connection, and clears stack-owned renderer/channel pointers. -`RemotingChannelClient` queues both protocol packages and terminal actions through the async renderer's ordered main-thread FIFO. A Core-authored `!Error` arrives through `OnReadError`, claims the first fatal error, and opens the native Yes/No prompt. Choosing Yes calls `ForceExitByFatelError()`; choosing No calls `RetainByFatalError(message)`, keeps the native renderer window open with a `[STOPPED]` title and fatal overlay, and exposes the error through renderer automation. A fatal local channel error has different UI semantics: after VlppOS's `IChannelClient` promotes a post-connection protocol error, `OnLocalError(..., true)` queues the ordinary disconnected transition directly, without showing a fatal prompt and without waiting for `OnDisconnected`. `OnDisconnected` queues the same idempotent transition when it is delivered. FIFO ordering lets an earlier `ControllerConnectionStopped` or Core `!Error` win before detach. +`RemoteProtocolRendererClient` queues both protocol packages and terminal actions through the async renderer's ordered main-thread FIFO. A Core-authored `!Error` arrives through `OnReadError`, claims the first fatal error, and opens the native Yes/No prompt. Choosing Yes calls `ForceExitByFatelError()`; choosing No calls `RetainByFatalError(message)`, keeps the native renderer window open with a `[STOPPED]` title and fatal overlay, and exposes the error through renderer automation. A fatal local channel error has different UI semantics: after VlppOS's `IChannelClient` promotes a post-connection protocol error, `OnLocalError(..., true)` queues the ordinary disconnected transition directly, without showing a fatal prompt and without waiting for `OnDisconnected`. `OnDisconnected` queues the same idempotent transition when it is delivered. FIFO ordering lets an earlier `ControllerConnectionStopped` or Core `!Error` win before detach. ### Protocol Stack Direction diff --git a/.github/KnowledgeBase/Learning.md b/.github/KnowledgeBase/Learning.md index f6a178e3..2fe8aa88 100644 --- a/.github/KnowledgeBase/Learning.md +++ b/.github/KnowledgeBase/Learning.md @@ -3,13 +3,13 @@ # Orders - Process staged tasks one by one with verification [19] -- Verify generated artifacts with downstream consumer checks [17] +- Verify generated artifacts with downstream consumer checks [19] - Crash early instead of adding error-tolerance fallbacks [14] - Port fixes from imports to source repositories [14] -- Proactively remove code made redundant by refactoring [12] -- Keep design documentation aligned with code after refactoring [10] +- Proactively remove code made redundant by refactoring [13] +- Keep design documentation aligned with code after refactoring [12] - Fix behavior at the owning state instead of patching symptoms [10] -- Extract abstractions only for real shared behavior [8] +- Extract abstractions only for real shared behavior [9] - Verify and localize portability on every target OS [7] - Make `Stop()` drain asynchronous work before returning [6] - Validate expectations against implementation and existing tests [5] diff --git a/.github/KnowledgeBase/manual/gacui/coding-agent/automation-service.md b/.github/KnowledgeBase/manual/gacui/coding-agent/automation-service.md index 3c21ac07..21602ffa 100644 --- a/.github/KnowledgeBase/manual/gacui/coding-agent/automation-service.md +++ b/.github/KnowledgeBase/manual/gacui/coding-agent/automation-service.md @@ -22,7 +22,7 @@ Feature availability is checked separately. A real service returns true from `Av ## Windows HTTP Layer -`StartWindowsHttpAutomationService` creates a localhost HTTP wrapper around the current `INativeAutomationService`. The test-support implementation lives in `Source/RemotingHelpers/AutomationService/Windows`, outside the ordinary `GacUI.Windows` library pair. Test applications consume it through the shared `Source_RemotingHelpers` project. +`StartWindowsHttpAutomationService` creates a localhost HTTP wrapper around the current `INativeAutomationService`. The test-support implementation lives in `Test/RemotingHelpers/AutomationService/Windows`, outside the ordinary `GacUI.Windows` library pair. Test applications consume it through the shared `Source_RemotingHelpers` project. The function takes `applicationName` as a URL path fragment and `port` as the localhost port. Given `applicationName == L"Automation/MyApp"` and `port == 8888`, the listener prefix is `http://localhost:8888/Automation/MyApp/`. The service offers exactly these HTTP URLs: - `GET http://localhost:8888/Automation/MyApp/Controls`: calls `DumpControlTree` on the UI thread when `CanDumpControlTree` is true. @@ -38,7 +38,7 @@ Each application owns the automation service and endpoint directly. After the se A normal Windows application can start the service before `GetApplication()->Run`: ```c++ -#include "../../../Source/RemotingHelpers/AutomationService/Windows/WindowsAutomationService.Windows.h" +#include "../../RemotingHelpers/AutomationService/Windows/WindowsAutomationService.Windows.h" using namespace vl; using namespace vl::presentation;