Merge branch 'main' into claude/objective-cartwright-8581ff

Author: tylerkron

src/Daqifi.Core.Tests/Communication/Transport/HidLibraryDeviceEnumeratorTests.cs

@@ -144,7 +144,7 @@ public FakeHidTransportDevice(
         public string? ProductName { get; }
         public bool IsConnected { get; private set; }
 
-        public void Open() => IsConnected = true;
+        public void Open(bool exclusive) => IsConnected = true;
 
         public void Close() => IsConnected = false;
 

src/Daqifi.Core.Tests/Communication/Transport/HidLibraryTransportTests.cs

@@ -33,6 +33,36 @@ public async Task ConnectAsync_WithMatchingDevice_OpensAndStoresMetadata()
         Assert.Equal(1, device.OpenCount);
     }
 
+    [Fact]
+    public async Task ConnectAsync_ByDefault_OpensDeviceShared()
+    {
+        var device = new FakeHidTransportDevice(0x04D8, 0x003C, "path-a", "SN-A");
+        var platform = new FakeHidPlatform([device]);
+
+        using var transport = new HidLibraryTransport(platform);
+
+        await transport.ConnectAsync(0x04D8, 0x003C);
+
+        // ExclusiveAccess defaults false so non-bootloader HID consumers keep a shared open.
+        Assert.False(transport.ExclusiveAccess);
+        Assert.False(device.LastOpenExclusive);
+    }
+
+    [Fact]
+    public async Task ConnectAsync_WhenExclusiveAccessSet_OpensDeviceExclusively()
+    {
+        var device = new FakeHidTransportDevice(0x04D8, 0x003C, "path-a", "SN-A");
+        var platform = new FakeHidPlatform([device]);
+
+        using var transport = new HidLibraryTransport(platform) { ExclusiveAccess = true };
+
+        await transport.ConnectAsync(0x04D8, 0x003C);
+
+        // A2: the bootloader flash must hold the HID handle exclusively. The flag is threaded to the
+        // device open so the stray-write guard (and discovery lockout) is actually requested.
+        Assert.True(device.LastOpenExclusive);
+    }
+
     [Fact]
     public async Task ConnectAsync_WithSerialFilter_SelectsMatchingDevice()
     {
@@ -76,6 +106,45 @@ public async Task ConnectAsync_WhenNoMatchingDevice_ThrowsIOException()
         await Assert.ThrowsAsync<IOException>(() => transport.ConnectAsync(0x04D8, 0x003C));
     }
 
+    [Fact]
+    public async Task ConnectByPathAsync_WithMatchingPath_OpensThatExactDevice()
+    {
+        // Two identical bootloaders (same VID/PID, no serial); only the path tells them apart.
+        var deviceA = new FakeHidTransportDevice(0x04D8, 0x003C, "path-a", string.Empty);
+        var deviceB = new FakeHidTransportDevice(0x04D8, 0x003C, "path-b", string.Empty);
+        var platform = new FakeHidPlatform([deviceA, deviceB]);
+
+        using var transport = new HidLibraryTransport(platform);
+
+        await transport.ConnectByPathAsync("path-b");
+
+        Assert.True(transport.IsConnected);
+        Assert.Equal("path-b", transport.DevicePath);
+        Assert.Equal(0, deviceA.OpenCount);
+        Assert.Equal(1, deviceB.OpenCount);
+    }
+
+    [Fact]
+    public async Task ConnectByPathAsync_WhenNoDeviceMatchesPath_ThrowsIOException()
+    {
+        var device = new FakeHidTransportDevice(0x04D8, 0x003C, "path-a", "SN-A");
+        var platform = new FakeHidPlatform([device]);
+        using var transport = new HidLibraryTransport(platform);
+
+        await Assert.ThrowsAsync<IOException>(() => transport.ConnectByPathAsync("path-z"));
+        Assert.False(transport.IsConnected);
+        Assert.Equal(0, device.OpenCount);
+    }
+
+    [Fact]
+    public async Task ConnectByPathAsync_WithEmptyPath_ThrowsArgumentException()
+    {
+        var platform = new FakeHidPlatform([]);
+        using var transport = new HidLibraryTransport(platform);
+
+        await Assert.ThrowsAsync<ArgumentException>(() => transport.ConnectByPathAsync("  "));
+    }
+
     [Fact]
     public async Task WriteAsync_WhenNotConnected_ThrowsInvalidOperationException()
     {
@@ -221,16 +290,18 @@ public FakeHidTransportDevice(int vendorId, int productId, string devicePath, st
 
         public int OpenCount { get; private set; }
         public int CloseCount { get; private set; }
+        public bool LastOpenExclusive { get; private set; }
         public int? LastWriteTimeoutMs { get; private set; }
         public int? LastReadTimeoutMs { get; private set; }
 
         public bool NextWriteResult { get; set; } = true;
         public HidTransportReadResult NextReadResult { get; set; }
             = HidTransportReadResult.Success(Array.Empty<byte>());
 
-        public void Open()
+        public void Open(bool exclusive)
         {
             OpenCount++;
+            LastOpenExclusive = exclusive;
             IsConnected = true;
         }
 

src/Daqifi.Core.Tests/Daqifi.Core.Tests.csproj

@@ -18,7 +18,7 @@
       <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
     </PackageReference>
     <PackageReference Include="coverlet.collector" Version="10.0.1" />
-    <PackageReference Include="Microsoft.NET.Test.Sdk" Version="18.6.0" />
+    <PackageReference Include="Microsoft.NET.Test.Sdk" Version="18.7.0" />
     <PackageReference Include="xunit" Version="2.9.3" />
     <PackageReference Include="xunit.runner.visualstudio" Version="3.1.5" />
   </ItemGroup>

src/Daqifi.Core.Tests/Firmware/FirmwareUpdateServiceTests.cs

@@ -134,6 +134,82 @@ [new HidDeviceInfo(0x04D8, 0x003C, "path-1", "SN-1", "DAQiFi Bootloader")]
         Assert.Contains(hidTransport.Writes, w => w.Length > 0 && w[0] == 0x44);
     }
 
+    [Fact]
+    public async Task UpdateFirmwareAsync_WithTargetDevicePath_FlashesThatExactBootloaderByPath()
+    {
+        // Multi-device: several identical bootloaders (same VID/PID, no serial) are enumerated at once.
+        // targetDevicePath must select and connect to that EXACT device by path — not VID/PID first-match.
+        var device = new FakeStreamingDevice("COM3");
+        var hidTransport = new FakeHidTransport();
+        hidTransport.EnqueueRead([0x01, 0x10]); // version
+        hidTransport.EnqueueRead([0x01, 0x02]); // erase ack
+        hidTransport.EnqueueRead([0x01, 0x03]); // program ack 1
+        hidTransport.EnqueueRead([0x01, 0x03]); // program ack 2
+        hidTransport.EnqueueRead([0xCD, 0xAB]); // READ_CRC response → 0xABCD (match)
+
+        var enumerator = new FakeHidDeviceEnumerator([
+            [
+                new HidDeviceInfo(0x04D8, 0x003C, "path-1", null, "DAQiFi Bootloader"),
+                new HidDeviceInfo(0x04D8, 0x003C, "path-2", null, "DAQiFi Bootloader")
+            ]
+        ]);
+
+        var bootloaderProtocol = new FakeBootloaderProtocol(
+            [[0xA1, 0x01], [0xA1, 0x02]],
+            crcRegions: [new FlashCrcRegion(0x9D000000, 256, 0xABCD)]);
+
+        var service = new FirmwareUpdateService(
+            hidTransport,
+            new FakeFirmwareDownloadService(),
+            new FakeExternalProcessRunner(),
+            NullLogger<FirmwareUpdateService>.Instance,
+            bootloaderProtocol,
+            enumerator,
+            CreateFastOptions());
+
+        var hexPath = CreateTempFile();
+        try
+        {
+            await service.UpdateFirmwareAsync(device, hexPath, progress: null, targetDevicePath: "path-2");
+        }
+        finally
+        {
+            File.Delete(hexPath);
+        }
+
+        Assert.Equal(FirmwareUpdateState.Complete, service.CurrentState);
+        Assert.Equal("path-2", hidTransport.LastConnectByPath);
+        Assert.Equal(1, hidTransport.ConnectByPathAttempts);
+        Assert.Equal(0, hidTransport.ConnectAttempts); // did NOT fall back to VID/PID first-match
+    }
+
+    [Fact]
+    public async Task UpdateFirmwareAsync_WithWhitespaceTargetDevicePath_ThrowsArgumentException()
+    {
+        // A whitespace target can never match an enumerated path, so fail fast instead of polling
+        // until the WaitingForBootloader timeout. (null target is allowed = untargeted.)
+        var service = new FirmwareUpdateService(
+            new FakeHidTransport(),
+            new FakeFirmwareDownloadService(),
+            new FakeExternalProcessRunner(),
+            NullLogger<FirmwareUpdateService>.Instance,
+            new FakeBootloaderProtocol([[0xA1, 0x01]]),
+            new FakeHidDeviceEnumerator([]),
+            CreateFastOptions());
+
+        var device = new FakeStreamingDevice("COM3");
+        var hexPath = CreateTempFile();
+        try
+        {
+            await Assert.ThrowsAsync<ArgumentException>(
+                () => service.UpdateFirmwareAsync(device, hexPath, progress: null, targetDevicePath: "   "));
+        }
+        finally
+        {
+            File.Delete(hexPath);
+        }
+    }
+
     [Fact]
     public async Task UpdateFirmwareAsync_WhenFlashCrcMismatches_FailsVerificationIntoFailedState()
     {
@@ -2060,6 +2136,24 @@ public void Connect(int vendorId, int productId, string? serialNumber = null)
             ConnectAsync(vendorId, productId, serialNumber).GetAwaiter().GetResult();
         }
 
+        public int ConnectByPathAttempts { get; private set; }
+        public string? LastConnectByPath { get; private set; }
+
+        public Task ConnectByPathAsync(string devicePath, CancellationToken cancellationToken = default)
+        {
+            cancellationToken.ThrowIfCancellationRequested();
+            ConnectByPathAttempts++;
+            LastConnectByPath = devicePath;
+            IsConnected = true;
+            DevicePath = devicePath;
+            return Task.CompletedTask;
+        }
+
+        public void ConnectByPath(string devicePath)
+        {
+            ConnectByPathAsync(devicePath).GetAwaiter().GetResult();
+        }
+
         public Task WriteAsync(byte[] data, CancellationToken cancellationToken = default)
         {
             cancellationToken.ThrowIfCancellationRequested();

src/Daqifi.Core/Communication/Transport/HidLibraryPlatform.cs

@@ -18,7 +18,10 @@ internal interface IHidTransportDevice
     string? ProductName { get; }
     bool IsConnected { get; }
 
-    void Open();
+    // When exclusive is true, request an exclusive open (Windows dwShareMode=0; macOS IOKit seize)
+    // so no other user-mode opener can open or write to the device while this handle is held.
+    // Best-effort: a refused exclusive open falls back to a shared open.
+    void Open(bool exclusive);
     void Close();
     bool Write(byte[] data, int timeoutMs);
     Task<bool> WriteAsync(byte[] data, int timeoutMs);
@@ -115,19 +118,86 @@ ex is ObjectDisposedException ||
         }
     }
 
-    public void Open()
+    public void Open(bool exclusive)
     {
         if (_stream != null)
         {
             return;
         }
 
-        if (!_device.TryOpen(out var stream) || stream == null)
+        HidStream? opened = null;
+        Exception? exclusiveOpenError = null;
+
+        if (exclusive)
+        {
+            // A2 (stray-write guard): open the bootloader's vendor collection exclusively
+            // (Windows dwShareMode=0) so no other user-mode opener — the desktop's own HID discovery
+            // loop, a second app instance, anything — can open or write to the device while this
+            // handle is held. The PIC32 bootloader's CRC check is disabled, so a stray SOH…EOT frame
+            // from another opener could be mis-parsed as an ERASE; the exclusive handle guards
+            // against that. A vendor-defined top-level collection (Usage Page 0xFF00) permits
+            // exclusive access, unlike the system keyboard/mouse collections hidclass keeps shared.
+            var exclusiveConfig = new OpenConfiguration();
+            exclusiveConfig.SetOption(OpenOption.Exclusive, true);
+
+            // Best-effort: a refused exclusive open falls through to the shared open below, so a flash
+            // that works today is never regressed by the added guard. This covers BOTH ways HidSharp can
+            // refuse — TryOpen returning false AND TryOpen throwing (e.g. a sharing-violation surfaced as
+            // an exception) — otherwise an exclusive-open throw would become a hard connection failure.
+            try
+            {
+                if (_device.TryOpen(exclusiveConfig, out var exclusiveStream) && exclusiveStream != null)
+                {
+                    opened = exclusiveStream;
+                }
+                else
+                {
+                    // TryOpen reported failure; dispose any partial stream so it isn't leaked.
+                    exclusiveStream?.Dispose();
+                }
+            }
+            catch (Exception ex)
+            {
+                // Exclusive open threw; remember why and leave opened == null so the shared open below
+                // is attempted. The cause is chained into the final throw if the shared open also fails.
+                exclusiveOpenError = ex;
+            }
+        }
+
+        if (opened == null)
         {
-            throw new IOException("Failed to open HID device.");
+            // The shared open can also throw (not just return false); catch it so a throwing shared
+            // fallback still routes through our normalized IOException and never drops the exclusive cause.
+            HidStream? sharedStream = null;
+            Exception? sharedOpenError = null;
+            try
+            {
+                if (!_device.TryOpen(out sharedStream) || sharedStream == null)
+                {
+                    // TryOpen reported failure; dispose any partial stream and fall through to the throw.
+                    sharedStream?.Dispose();
+                    sharedStream = null;
+                }
+            }
+            catch (Exception ex)
+            {
+                sharedOpenError = ex;
+            }
+
+            if (sharedStream == null)
+            {
+                // Both opens failed — preserve whatever cause(s) we have. When both threw, chain both via
+                // an AggregateException so neither root cause is lost for diagnosis.
+                var cause = exclusiveOpenError != null && sharedOpenError != null
+                    ? new AggregateException(exclusiveOpenError, sharedOpenError)
+                    : sharedOpenError ?? exclusiveOpenError;
+                throw new IOException("Failed to open HID device.", cause);
+            }
+
+            opened = sharedStream;
         }
 
-        _stream = stream;
+        _stream = opened;
     }
 
     public void Close()