Refactor Sample app to be a thin, stateless test harness

Author: thargy

docs/plans/2026-05-19-sample-app-refactoring-plan.md

@@ -0,0 +1,59 @@
+# Refactoring Plan: Thin Sample CLI App
+
+To ensure the Sample CLI application behaves as a high-fidelity test harness, we must eliminate all duplicated state-tracking (`_pins`, `_lastValues`) and custom validation logic in `Program.cs` that mirrors code in the driver or simulation engine. Instead, the application should delegate completely to the native APIs and error-handling of the customized `System.Device.Gpio` shim.
+
+---
+
+## Principles
+
+1. **Preserve Mirror-Image APIs**: The custom `System.Device.Gpio` shims must mirror the official dotnet API perfectly. We do not add custom APIs (like `GetOpenPins`) to the shimmed classes.
+2. **Stateless Test Harness**: The CLI app does not need to duplicate open/close or value state tracking. It should just naively invoke methods (e.g. `controller.OpenPin(...)`, `controller.Write(...)`) and let the driver/engine handle all boundary validations, propagating standard .NET exceptions (like `InvalidOperationException`) back to the CLI shell.
+3. **Stateless Pin Status**: To support the `status` command without introducing non-standard APIs to `GpioController`, we can simply query the standard `controller.IsPinOpen(pin)` API in a loop from pin 1 to 40 (the typical Raspberry Pi header range). This gives us a 100% compliant, standard-compatible status query.
+
+---
+
+## Refactoring Program.cs to be Thin
+
+We will clean up and rebuild `Program.cs` to eliminate duplicate state management, background thread polling, and manual validation.
+
+### 1. Eliminate Fields & Background Work
+- Delete `_pins` dictionary.
+- Delete `_lastValues` dictionary.
+- Remove `WatchInputPins` background polling method.
+- Remove `_watcherCts` and `_watcherTask`.
+
+### 2. Event-Driven Input Tracking
+- Keep a reactive value change listener using the standard event callbacks:
+```csharp
+        private static void OnPinValueChanged(object sender, PinValueChangedEventArgs args)
+        {
+            PinValue val = _controller.Read(args.PinNumber);
+            lock (_consoleLock)
+            {
+                Console.ForegroundColor = ConsoleColor.Magenta;
+                Console.Write($"\n[ALERT] Input state changed: Pin {args.PinNumber} is now {val}!");
+                Console.ResetColor();
+                PrintPrompt();
+            }
+        }
+```
+- In `OpenPin` helper, register the callback if the mode is an input mode.
+- In `ClosePin` helper, unregister the callback.
+- In the `setmode` / `sm` command, unregister first, change mode, and register if it became input.
+
+### 3. Delegate Commands directly to GpioController
+- **`scheme`**: Reset scheme by reinstantiating `_controller` without needing to clear local state.
+- **`open`**: Call `OpenPin` directly. Let the controller/driver validate.
+- **`close`**: Call `ClosePin` directly. Let the controller/driver validate open status.
+- **`write`**: Convert input value to `PinValue` and call `controller.Write` directly. Let the driver/engine throw if invalid or unauthorized.
+- **`read`**: Call `controller.Read` directly.
+- **`setmode`**: Set the mode directly. Manage callbacks reactively.
+- **`status`**: Loop through pin 1 to 40, check `controller.IsPinOpen(pin)` naively, and print the current mode and value using only standard `GpioController` methods!
+
+---
+
+## Verification Plan
+
+1. **Compilation**: Run `dotnet build` to verify clean compilation of all libraries and the sample application.
+2. **Unit Tests**: Run `dotnet test` to ensure existing driver and engine tests pass perfectly.
+3. **Interactive Testing**: Run the Sample app, open output/input pins, toggle values from both the CLI and the Web UI, and verify that the alerts and commands reflect state in real-time.

src/DevDecoder.GpioSimulator.Sample/CommandAutoCompleteHandler.cs

@@ -0,0 +1,95 @@
+using System;
+using System.Collections.Generic;
+using System.Linq;
+
+namespace DevDecoder.GpioSimulator.Sample
+{
+    /// <summary>
+    /// Provides auto-completion suggestions for the interactive GPIO board simulator terminal.
+    /// </summary>
+    public class CommandAutoCompleteHandler : IAutoCompleteHandler
+    {
+        private static readonly string[] Commands =
+        {
+            "open", "close", "write", "read", "setmode", "isopen", 
+            "issupported", "scheme", "schema", "status", "help", 
+            "exit", "quit"
+        };
+
+        private static readonly string[] Modes = { "in", "out", "pullup", "pulldown" };
+        private static readonly string[] Schemes = { "logical", "board" };
+        private static readonly string[] WriteValues = { "1", "0", "high", "low" };
+
+        /// <summary>
+        /// Gets or sets the characters that define the boundary for word separations.
+        /// </summary>
+        public char[] Separators { get; set; } = new char[] { ' ' };
+
+        /// <summary>
+        /// Generates auto-completion suggestions based on the current input text and cursor index.
+        /// </summary>
+        /// <param name="text">The current input line text.</param>
+        /// <param name="index">The current cursor index.</param>
+        /// <returns>An array of suggestions matching the context.</returns>
+        public string[] GetSuggestions(string text, int index)
+        {
+            if (string.IsNullOrEmpty(text))
+            {
+                return Commands;
+            }
+
+            // Split the line by spaces
+            string[] parts = text.Split(Separators, StringSplitOptions.None);
+            if (parts.Length == 0)
+            {
+                return Commands;
+            }
+
+            string cmd = parts[0].ToLower();
+
+            // If we're typing the first word (command)
+            if (parts.Length == 1)
+            {
+                return Commands.Where(c => c.StartsWith(cmd, StringComparison.OrdinalIgnoreCase)).ToArray();
+            }
+
+            // Auto-complete sub-commands or parameters
+            // Case 1: scheme/schema parameter autocomplete (e.g., scheme <tab>)
+            if ((cmd == "scheme" || cmd == "schema") && parts.Length == 2)
+            {
+                string arg = parts[1].ToLower();
+                return Schemes.Where(s => s.StartsWith(arg, StringComparison.OrdinalIgnoreCase)).ToArray();
+            }
+
+            // Case 2: open <pin> <mode> -> parts[2] is the mode
+            if (cmd == "open" && parts.Length == 3)
+            {
+                string arg = parts[2].ToLower();
+                return Modes.Where(m => m.StartsWith(arg, StringComparison.OrdinalIgnoreCase)).ToArray();
+            }
+
+            // Case 3: setmode <pin> <mode> / set <pin> <mode> -> parts[2] is the mode
+            if ((cmd == "setmode" || cmd == "set" || cmd == "sm") && parts.Length == 3)
+            {
+                string arg = parts[2].ToLower();
+                return Modes.Where(m => m.StartsWith(arg, StringComparison.OrdinalIgnoreCase)).ToArray();
+            }
+
+            // Case 4: issupported <pin> <mode> -> parts[2] is the mode
+            if ((cmd == "issupported" || cmd == "is") && parts.Length == 3)
+            {
+                string arg = parts[2].ToLower();
+                return Modes.Where(m => m.StartsWith(arg, StringComparison.OrdinalIgnoreCase)).ToArray();
+            }
+
+            // Case 5: write <pin> <value> -> parts[2] is the value
+            if ((cmd == "write" || cmd == "w") && parts.Length == 3)
+            {
+                string arg = parts[2].ToLower();
+                return WriteValues.Where(v => v.StartsWith(arg, StringComparison.OrdinalIgnoreCase)).ToArray();
+            }
+
+            return Array.Empty<string>();
+        }
+    }
+}

src/DevDecoder.GpioSimulator.Sample/DevDecoder.GpioSimulator.Sample.csproj

@@ -19,6 +19,7 @@
       <PrivateAssets>all</PrivateAssets>
       <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
     </PackageReference>
+    <PackageReference Include="ReadLine" Version="2.0.1" />
   </ItemGroup>
 
 </Project>