Implement ICorDebug integration for Run with Debug (#86)

Author: Copilot

.github/agents/basicAgent.agent.md

@@ -16,6 +16,8 @@ description: Used for general purpose NodeDev development
 4) Document newly added content or concepts in this `.github/agents/basicAgent.agent.md` file or any related documentation file.
 5) When the user corrects major mistakes done during your development, document them in this file to ensure it is never done again.
 6) You must always install playwright BEFORE trying to run the tests. build the projects and install playwright. If you struggle (take multiple iterations to do it), document the steps you took in this file to make it easier next time.
+7) **ALWAYS read the E2E testing documentation (`docs/e2e-testing.md`) BEFORE making any changes to E2E tests.** This documentation contains critical information about test patterns, selector strategies, and troubleshooting.
+8) **When encountering E2E test issues (timeouts, element not found, etc.), ALWAYS use the Playwright MCP tools** to take screenshots and inspect the page state before assuming the test or functionality is broken. Use `playwright-browser_snapshot` and `playwright-browser_take_screenshot` to validate element visibility and page state.
 
 ## Programming style
 
@@ -39,10 +41,11 @@ NodeDev is a visual programming environment built with Blazor and Blazor.Diagram
 
 ### UI Structure
 The main UI consists of:
-- **AppBar**: Top toolbar with project controls (New, Open, Save, Options)
+- **AppBar**: Top toolbar with project controls (New, Open, Save, Options, Run, Run with Debug)
 - **ProjectExplorer**: Left panel showing project structure (classes, methods, properties)
 - **GraphCanvas**: Central canvas where nodes are placed and connected
 - **ClassExplorer**: Shows details of the currently selected class
+- **DebuggerConsolePanel**: Bottom panel with tabs for Console Output and Debug Callbacks
 
 ### Graph System
 - Uses Blazor.Diagrams library for visual node editing
@@ -128,27 +131,82 @@ Detailed topic-specific documentation is maintained in the `docs/` folder:
 
 ## Debugging Infrastructure
 
+### Hard Debugging (ICorDebug)
+NodeDev now supports "Hard Debugging" via the ICorDebug API (.NET's unmanaged debugging interface). This provides low-level debugging capabilities including:
+- Process attachment and management
+- Debug event callbacks (process creation, module loading, thread creation, etc.)
+- Future support for breakpoints and step-through execution
+
+**Running with Debug:**
+The UI provides two run modes:
+1. **Run** - Normal execution without debugger attachment
+2. **Run with Debug** - Executes with ICorDebug debugger attached
+
+**Important**: "Run with Debug" requires successful debugger attachment. If attachment fails for any reason (DbgShim not found, CLR enumeration fails, etc.), the operation will fail with an error dialog showing the specific issue. There is no fallback to normal execution.
+
+**Debug State Management:**
+- `Project.IsHardDebugging` - Boolean property indicating active debug session
+- `Project.DebuggedProcessId` - Process ID of debugged process (null when not debugging)
+- `Project.HardDebugStateChanged` - Observable stream for debug state changes (true when attached, false when detached)
+- `Project.DebugCallbacks` - Observable stream of `DebugCallbackEventArgs` for all debug events
+
+**UI Visual Feedback:**
+- "Run with Debug" button changes color (warning) and shows PID when debugging
+- Button is disabled during active debug session
+- DebuggerConsolePanel shows two tabs:
+  - "Console Output" - Standard output from the program
+  - "Debug Callbacks" - Real-time debug events with timestamps
+
+**Implementation Pattern:**
+```csharp
+// Running with debug in Project.cs
+try 
+{
+    var result = project.RunWithDebug(BuildOptions.Debug);
+}
+catch (InvalidOperationException ex)
+{
+    // Handle debug attachment failure
+    // Show error dialog to user with ex.Message
+    Console.WriteLine($"Debug failed: {ex.Message}");
+}
+
+// Subscribing to debug callbacks
+project.DebugCallbacks.Subscribe(callback => {
+    Console.WriteLine($"{callback.CallbackType}: {callback.Description}");
+});
+
+// Subscribing to debug state changes
+project.HardDebugStateChanged.Subscribe(isDebugging => {
+    if (isDebugging)
+        Console.WriteLine("Debugging started");
+    else
+        Console.WriteLine("Debugging stopped");
+});
+```
+
 ### Debugger Module (NodeDev.Core.Debugger)
 The debugging infrastructure is located in `src/NodeDev.Core/Debugger/` and provides ICorDebug API access via the ClrDebug NuGet package:
 
 - **DbgShimResolver**: Cross-platform resolution for the dbgshim library from NuGet packages or system paths
 - **DebugSessionEngine**: Main debugging engine with process launch, attach, and callback handling
-- **ManagedDebuggerCallbacks**: Implementation of ICorDebugManagedCallback interfaces
+- **ManagedDebuggerCallbacks**: Implementation of ICorDebugManagedCallback interfaces via ClrDebug
 - **DebugEngineException**: Custom exception type for debugging errors
 
 **Dependencies:**
 - `ClrDebug` (v0.3.4): C# wrappers for the unmanaged ICorDebug API
 - `Microsoft.Diagnostics.DbgShim` (v9.0.652701): Native dbgshim library for all platforms
 
 ### ScriptRunner
-NodeDev includes a separate console application called **ScriptRunner** that serves as the target process for debugging. This architecture is being developed to support "Hard Debugging" via the ICorDebug API (.NET's unmanaged debugging interface).
+NodeDev includes a separate console application called **ScriptRunner** that serves as the target process for debugging. This architecture supports "Hard Debugging" via the ICorDebug API.
 
 **Architecture:**
 - **Host Process**: The Visual IDE (NodeDev.Blazor.Server or NodeDev.Blazor.MAUI)
 - **Target Process**: ScriptRunner - a separate console application that executes the user's compiled code
 
 **ScriptRunner Features:**
 - Accepts a DLL path as command-line argument
+- Optional `--wait-for-debugger` flag to pause execution until debugger attaches
 - Loads assemblies using `Assembly.LoadFrom()`
 - Finds and invokes entry points:
   - Static `Program.Main` method (in any namespace)
@@ -160,12 +218,5 @@ NodeDev includes a separate console application called **ScriptRunner** that ser
 - ScriptRunner is automatically built with NodeDev.Core
 - MSBuild targets copy ScriptRunner to the output directory of dependent projects
 - The `Project.Run()` method automatically locates and launches ScriptRunner
+- The `Project.RunWithDebug()` method launches ScriptRunner and attaches debugger
 - The `Project.GetScriptRunnerPath()` method returns the ScriptRunner location for debugging infrastructure
-
-**Future: ICorDebug Integration**
-This infrastructure prepares NodeDev for implementing advanced debugging features:
-- Breakpoints in visual graphs
-- Step-through execution
-- Variable inspection at runtime
-- Exception handling and catching
-- Live debugging across process boundaries

.github/workflows/dotnet.yml

@@ -13,7 +13,7 @@ jobs:
   build:
     name: Build the entire solution
     uses: ./.github/workflows/workflow-build.yml
-
+    
   tests:
     name: Run Unit Tests
     needs: build
@@ -24,3 +24,12 @@ jobs:
     needs: build
     uses: ./.github/workflows/workflow-e2e-tests.yml 
 
+  tests-windows:
+    name: Run Unit Tests (Windows)
+    needs: build
+    uses: ./.github/workflows/workflow-tests-windows.yml
+
+  e2e-tests-windows:
+    name: Run End To End Tests (Windows)
+    needs: build
+    uses: ./.github/workflows/workflow-e2e-tests-windows.yml

.github/workflows/workflow-build.yml

@@ -17,13 +17,13 @@ jobs:
       with:
         dotnet-version: 10.0.x
 
-    - name: Restore .NET dependencies
+    - name: Install workloads
       working-directory: ./src
-      run: dotnet restore
+      run: dotnet workload restore
 
     - name: Build
       working-directory: ./src
-      run: dotnet build --no-restore
+      run: dotnet build -c Release
 
     - name: Upload Build Artifact
       uses: actions/upload-artifact@v4

.github/workflows/workflow-e2e-tests-windows.yml

@@ -20,19 +20,19 @@ jobs:
 
     - name: Build Necessary for Playwright
       working-directory: ./src/NodeDev.EndToEndTests
-      run: dotnet build
+      run: dotnet build -c Release
 
     - name: Allow run
       run: chmod -R +x ./src/NodeDev.Blazor.Server/bin
 
     - name: Ensure browsers are installed
-      run: pwsh ./src/NodeDev.EndToEndTests/bin/Debug/net10.0/playwright.ps1 install --with-deps
+      run: pwsh ./src/NodeDev.EndToEndTests/bin/Release/net10.0/playwright.ps1 install --with-deps
 
     - name: Test
       env:
         HEADLESS: true
       working-directory: ./src/NodeDev.EndToEndTests
-      run: dotnet test --no-build --verbosity normal
+      run: dotnet test -c Release --no-build --verbosity normal
 
     - name: Upload std Artifact
       if: failure()

.github/workflows/workflow-e2e-tests.yml

@@ -20,19 +20,19 @@ jobs:
 
     - name: Build Necessary for Playwright
       working-directory: ./src/NodeDev.EndToEndTests
-      run: dotnet build
+      run: dotnet build -c Release
 
     - name: Allow run
       run: chmod -R +x ./src/NodeDev.Blazor.Server/bin
 
     - name: Ensure browsers are installed
-      run: pwsh ./src/NodeDev.EndToEndTests/bin/Debug/net10.0/playwright.ps1 install --with-deps
+      run: pwsh ./src/NodeDev.EndToEndTests/bin/Release/net10.0/playwright.ps1 install --with-deps
 
     - name: Test
       env:
         HEADLESS: true
       working-directory: ./src/NodeDev.EndToEndTests
-      run: dotnet test --no-build --verbosity normal
+      run: dotnet test -c Release --no-build --verbosity normal
 
     - name: Upload std Artifact
       if: failure()

.github/workflows/workflow-tests-windows.yml

@@ -24,4 +24,4 @@ jobs:
 
     - name: Test
       working-directory: ./src/NodeDev.Tests
-      run: dotnet test --no-build --verbosity normal
+      run: dotnet test -c Release --no-build --verbosity normal

.github/workflows/workflow-tests.yml

@@ -24,4 +24,4 @@ jobs:
 
     - name: Test
       working-directory: ./src/NodeDev.Tests
-      run: dotnet test --no-build --verbosity normal
+      run: dotnet test -c Release --no-build --verbosity normal

docs/e2e-testing.md

@@ -226,6 +226,29 @@ Components are marked with `data-test-id` attributes for reliable selection:
 - `graph-node`: Individual nodes (with `data-test-node-name` for the node name)
 - Graph ports are located by CSS class and port name
 
+### MudBlazor Component Selectors
+
+**IMPORTANT**: MudBlazor components like `MudTabPanel` do NOT forward custom attributes like `data-test-id` to the rendered HTML. For these components, use CSS classes instead:
+
+```razor
+<!-- WRONG - data-test-id won't work on MudTabPanel -->
+<MudTabPanel Text="Console Output" data-test-id="consoleOutputTab">
+
+<!-- CORRECT - use Class attribute instead -->
+<MudTabPanel Text="Console Output" Class="consoleOutputTab">
+```
+
+In tests, select by CSS class:
+```csharp
+// Use CSS class selector for MudBlazor components that don't forward data-test-id
+var consoleOutputTab = Page.Locator(".consoleOutputTab");
+```
+
+**Always verify your selectors work** by using Playwright tools to inspect the page:
+1. Use `playwright-browser_snapshot` to see the accessibility tree
+2. Use `playwright-browser_take_screenshot` to visually inspect the page
+3. If a selector doesn't find elements, the attribute may not be rendered - check the actual HTML
+
 ## Running Tests
 
 ### Locally
@@ -244,9 +267,26 @@ Tests run automatically in GitHub Actions with headless mode enabled.
 3. **Validate with screenshots**: Capture screenshots during critical operations
 4. **Test incrementally**: Start with simple movements before complex scenarios
 5. **Account for grid snapping**: Node positions may snap to grid, use tolerance in assertions
+6. **ALWAYS read this documentation BEFORE modifying E2E tests**
+7. **NEVER skip, disable, or remove tests** - fix the underlying issue instead
 
 ## Troubleshooting
 
+### ⚠️ IMPORTANT: Always Use Playwright Tools First
+
+**When encountering any E2E test issues (timeout, element not found, assertion failures), ALWAYS use the Playwright MCP tools to diagnose before assuming the test or functionality is broken:**
+
+1. **`playwright-browser_snapshot`** - Get accessibility tree of current page state
+2. **`playwright-browser_take_screenshot`** - Capture visual screenshot to see actual UI state
+3. **`playwright-browser_navigate`** - Manually navigate to test the UI
+4. **`playwright-browser_click`** - Test interactions manually
+
+These tools help you:
+- Verify elements exist and are visible
+- See the actual HTML/CSS classes rendered (important for MudBlazor components)
+- Understand timing issues by inspecting state at specific moments
+- Validate selectors before assuming they're correct
+
 ### Nodes Don't Move
 - Verify the node name matches exactly (case-sensitive)
 - Check if node is visible on canvas before dragging

src/NodeDev.Blazor/Components/DebuggerConsolePanel.razor

@@ -3,10 +3,24 @@
 	<MudPaper Class="w100 pa-1 overflow-y-scroll d-flex flex-column relative" Style="height: 200px" data-test-id="consolePanel">
 		<MudIconButton Icon="@MudBlazor.Icons.Material.Filled.ArrowDropDown" Class="absolute" Style="right: 0px; top: 0px" Size="Size.Small" OnClick="@(() => IsShowing = false)"></MudIconButton>
 
-		@foreach (var line in Lines.Reverse())
-		{
-			<span class="w100" data-test-id="consoleLine">@line</span>
-		}
+		<MudTabs Elevation="0" Rounded="false" Class="w100 h100 consoleTabs">
+			<MudTabPanel Text="Console Output" Class="consoleOutputTab">
+				<div class="w100 h100 overflow-y-scroll d-flex flex-column-reverse">
+					@foreach (var line in Lines.Reverse())
+					{
+						<span class="w100 consoleLine">@line</span>
+					}
+				</div>
+			</MudTabPanel>
+			<MudTabPanel Text="Debug Callbacks" Class="debugCallbacksTab">
+				<div class="w100 h100 overflow-y-scroll d-flex flex-column-reverse">
+					@foreach (var callback in DebugCallbacks.Reverse())
+					{
+						<span class="w100 debugCallbackLine">@callback</span>
+					}
+				</div>
+			</MudTabPanel>
+		</MudTabs>
 	</MudPaper>
 
 }

src/NodeDev.Blazor/Components/DebuggerConsolePanel.razor.cs

@@ -1,5 +1,6 @@
 using Microsoft.AspNetCore.Components;
 using NodeDev.Core;
+using NodeDev.Core.Debugger;
 using System.Reactive.Subjects;
 
 
@@ -12,10 +13,12 @@ public partial class DebuggerConsolePanel : ComponentBase, IDisposable
 
 	private IDisposable? GraphExecutionChangedDisposable;
 	private IDisposable? ConsoleOutputDisposable;
+	private IDisposable? DebugCallbackDisposable;
 
 	private TextWriter? PreviousTextWriter;
 
 	private readonly ReverseQueue Lines = new(10_000);
+	private readonly ReverseQueue DebugCallbacks = new(10_000);
 	private string LastLine = ">";
 
 	private bool IsShowing = false;
@@ -31,11 +34,13 @@ protected override void OnInitialized()
 
 		GraphExecutionChangedDisposable = Project.GraphExecutionChanged.Subscribe(OnGraphExecutionChanged);
 		ConsoleOutputDisposable = Project.ConsoleOutput.Subscribe(OnConsoleOutput);
+		DebugCallbackDisposable = Project.DebugCallbacks.Subscribe(OnDebugCallback);
 	}
 
 	public void Clear()
 	{
 		Lines.Clear();
+		DebugCallbacks.Clear();
 		LastLine = ">";
 	}
 
@@ -60,6 +65,14 @@ private void OnConsoleOutput(string text)
 		AddText(text);
 	}
 
+	private void OnDebugCallback(DebugCallbackEventArgs args)
+	{
+		var timestamp = DateTime.Now;
+		var callbackInfo = new DebugCallbackInfo(timestamp, args.CallbackType, args.Description);
+		DebugCallbacks.Enqueue(callbackInfo.ToString());
+		RefreshRequiredSubject.OnNext(null);
+	}
+
 	private void AddText(string text)
 	{
 		var newLineCharacterIndex = text.IndexOf('\r');
@@ -90,6 +103,7 @@ public void Dispose()
 
 		GraphExecutionChangedDisposable?.Dispose();
 		ConsoleOutputDisposable?.Dispose();
+		DebugCallbackDisposable?.Dispose();
 		RefreshRequiredDisposable?.Dispose();
 
 		if (PreviousTextWriter != null)
@@ -99,6 +113,11 @@ public void Dispose()
 		}
 	}
 
+	private record DebugCallbackInfo(DateTime Timestamp, string Type, string Description)
+	{
+		public override string ToString() => $"[{Timestamp:HH:mm:ss.fff}] {Type}: {Description}";
+	}
+
 	private class ControlWriter : TextWriter
 	{
 		private Action<string> AddText;