Fix and Optimize Configuration, SSH Key Handling, and UI (#21)

* Fix startup error when files are not readable.

* Added Winget Pipeline

* Extended FileInfoWindow

* Implemented PasswordBox with toggleable password visibility

* Update CI

* Minor version bump

* Added Password in File Info view

* Introduced object for BasicSshKeyFileInformation

* Reniced SshKeyFileInformation.cs

* Fixes some errors in SshKeyFileInformation.cs; Updated file reading logic for ppk files

* Removed obsolete comments

* Refactoring #1

* fixed reactive chain

* 😁

* Optimized Reactive chains

* -

* Added new icon, changed resolverchain

* Refactor icon size handling, improve SSH key collection tracking, and update reactive bindings.

* Relocate and optimize asset management: replace SVG icon with ICO format, restructure image paths, and update project references accordingly.

* Add light theme assets, theme selection settings, and dynamic icon support.

* Refactor theme resources, improve reactive property bindings, update dependencies, and enhance SSH key file handling logic.

* Refactor SubmitButtons as reusable control, replace redundant button definitions, and apply dynamic theme resources.

* Add SubmitButtons control to EditKnownHostsWindow.axaml

* Removed obsolete Interfaces

* Minor fixes

* Adjust Colors throughout the application

* removed logger from SshKeyFilePassword.cs

* Changes on FileInfoWindow

* Color occurences changed to dynamic resource

* Update ReactiveUI

* Started to implement password change

* Implemented password change ability

* Disabled selection of items in SshKeyComboBoxStyle, when they are not initialized

* Changed writing and disabled false-positive error in SshKeyItemContainerTheme

* Implemented retry abort mechanism

* Reformat & Cleanup; Changed to ServerConnection.cs

* Changes in ConnectToServerViewModel

* Removed redundant interfaces; reformat & cleanup

* Implemented headered item

* Minor refactoring in server handling

* added ideas and refactoring suggestions

* Refactoring of SshKeyManager.cs

* Cleanup of old Extensions, compute fingerprint by ourselfs - even if key is encrypted

* Enabled Logging by SSH.NET

* Refactoring progress

* Refactoring Progress #2

* SshKeyFileInformation changed to OAPHs

* not working sorter

* Update package dependencies across all projects to latest stable versions

* Remove custom Sorter control, migrate to Avalonia DataGrid for key listing adjustments

* Replace ContextMenus with FlyoutButtons, update styling and font sizes, and add Xaml.Behaviors.Avalonia dependency.

* Add font size adjustment feature to Application Settings with binding and reset option.

* Add dynamic font size management with resource observables, MaterialIcon size adjustments, and NumericUpDown control in Application Settings.

* Refactor icon size handling: adjust MaterialIconSize resource, streamline size-related properties, and improve logging logic.

* Update DataGrid column properties, add loading spinner, and improve reactive processing state handling.

* Update localization bindings for tab headers, improve string resource handling, and streamline German translations.

* Refactor SSH key export logic: simplify case handling, improve error messaging, and update dynamic window title formatting.

* Refactor reactive properties and commands: streamline syntax, enhance property accessibility, and improve dynamic window title logic.

* Refactor ViewModelBase hierarchy: simplify generics, remove redundant logger dependencies, and streamline initialization patterns.

* Refactor various components: optimize property and method signatures, streamline placeholders and localization, and remove redundant dependencies.

* Refactor KnownHostsFile and related components: optimize initialization, enhance file handling logic, and streamline key export functionality.

* Refactor KnownHosts handling: optimize file updates, consolidate constructors, and streamline bindings in KnownHosts GUI rendering.

* Optimize AuthorizedKeys handling: add change detection for file updates, prevent unnecessary writes to file and server, and fix BUG comment.

* Refactor dependency injection tests: use DryIoc container directly and refine registration logic to improve clarity and accuracy.

* Add `Window_OnClosing` handler for dialogs, adjust window properties, and include ReactiveUI references in project.

* add todo;

* Prevent window closing interruptions: handle `Window_OnClosing` to cancel external close attempts and streamline closing logic.

* Refactor ApplicationSettings components: enhance UI alignment properties, add "Open Cache Folder" command, and streamline font size initialization logic.

* Refactor SshKeyManager file watcher: integrate Avalonia Dispatcher for UI thread invocation and streamline event handling logic.

* Refactor dialog closing logic: introduce `_isInternalClose` flag to prevent external close interruptions and streamline event handling. Optimize reactive properties in `SshKeyFileInformation` for better initialization and UI thread integration.

* Refactor `SshKeyFileInformation`: remove reactive properties and disposables to simplify initialization and make properties immutable.

* Refactor `FlyoutButton` UI: simplify tooltip and key count display logic, remove spinning icon animation, and streamline related ViewModel properties.

* Refactor `ApplicationSettingsWindow`: update UI for cache options, enhance layout alignment, and remove unused reactive properties in ViewModel.

* Replace DryIoc with Microsoft.Extensions.DependencyInjection for dependency injection, update related service registrations, and refactor impacted components accordingly.

* Adjust DependencyInjectionExtensions

* Cleanuip Dialoghost

* Fix icon store filling

* Reformat & Cleanup

* small fixes

* Added processing animation

* Icon Updates

* Added some findings, need more.

* Update package dependencies to latest versions and improve DI test robustness

* Refactor key file format handling: simplify `Password.Set` logic, update binding properties for key formats, clean up TODOs, and enhance backup file deletion logic.

* Refactor and modularize SSH key management: introduce new interfaces and services (`IDirectoryCrawler`, `IKeyFileBackupService`, `IKeyFileWriterService`, and `ISshKeyGenerator`), implement `SshKeyFactory` and `KeyFileBackupService`, and update `SshKeyManager` to use dependency injection and improve maintainability.

* Simplify "Provide Password" button in SshKeyFileStyle and fix export format in MainWindowViewModel.

* Update ReactiveUI and ReactiveUI.SourceGenerators to latest versions in project files.

* Add TODO comment to enable scanning of additional user-scoped paths in DirectoryCrawler.

* Added AppConfiguration; Added WriteableConfiguration interface

* Added writeableconfig to appsettingsviewmodel

* Restrict ComboBoxItem binding in SshKeyFileStyle and remove redundant DataType specification.

* Refactor DirectoryCrawler to support async disk enumeration and enable scanning of configurable lookup paths.

* Add `PathExtensions` utility class for file/directory management and integrate usage into configuration and logging workflows.

* Added ComboBox for path selection in AddKeyWindow and font size binding adjustments

* Ensure main window is brought to front on open, then clear topmost flag

* Refactor configuration system: replaced `IWritableConfiguration` with `IMutableConfiguration`, updated usages across the app, and improved settings UI layout.

* Refactor SSH key file format handling: replace `SshKeyFormatExtension` constants with `PathExtensions`, add missing utility functions, and update references across the codebase.

* Add lookup path management in ApplicationSettings: enable adding and removing paths with UI integration and validation logic

* Refactor ApplicationSettings: enhance lookup path management, implement new bindings for HeaderedItem, throttle reactive commands, and extract `PathDeletableConverter` to a dedicated file.

* Refactor application configuration: update font size type to `double`, introduce `ApplyConfiguration` method for dynamic theme and log level application, and optimize reactive bindings in `ApplicationSettingsViewModel`.

* Add `CollectionIndexConverter` for 1-based indexing in lookup paths and update `ApplicationSettingsWindow` bindings to include index display

* Update `ApplicationSettingsWindow`: localize lookup paths header text and add German translation

* Add `TooltippedIcon` control and integrate it into `ApplicationSettingsWindow` for enhanced UI element descriptions

* Add hover-based tooltip functionality to `TooltippedIcon` with extended pointer handling and popup interactions

* Update dependencies: bump Avalonia packages to 12.0.2, ReactiveUI to 23.2.27, and other minor version upgrades

* clean up indentation, adjust formatting across services and views, and streamline property definitions.

* Centralize NuGet package version management and refactor project files to improve readability and reduce redundancy.

* Fix SSH key format detection: ensure `.EndsWith` is used for extension comparison to handle edge cases

Author: frequency403

.github/workflows/auto-tag.yml

@@ -2,7 +2,7 @@ name: Auto-Tag on Release Merge
 
 on:
   pull_request:
-    types: [closed]
+    types: [ closed ]
     branches:
       - master
       - main

.github/workflows/build.yml

@@ -68,6 +68,7 @@ jobs:
       - name: Build AppImage
         if: matrix.target == 'linux-x64'
         run: |
+          APPSTREAM_VERSION="${GITHUB_REF_NAME#v}"
           # Download appimagetool
           wget -q https://github.com/AppImage/appimagetool/releases/download/continuous/appimagetool-x86_64.AppImage -O appimagetool
           chmod +x appimagetool
@@ -147,8 +148,8 @@ jobs:
 
       - name: Prepare extra assets
         run: |
-          cp OpenSSH_GUI/Assets/appicon.png artifacts/
-          cp LICENSE artifacts/
+          cp OpenSSH_GUI/Assets/appicon.png artifacts/appicon.png   # ← Name explizit
+          cp LICENSE artifacts/LICENSE
 
       # Create a single release and upload all files from the 'artifacts' directory
       - name: Create Release and Upload Assets
@@ -177,7 +178,7 @@ jobs:
         with:
           name: OpenSSH-GUI-linux-x64
           path: ./
-          
+
       - name: Download generated desktop file
         uses: actions/download-artifact@v4
         with:
@@ -191,11 +192,9 @@ jobs:
           SHA_ICON=$(sha256sum OpenSSH_GUI/Assets/appicon.png | cut -d' ' -f1)
           SHA_DESKTOP=$(sha256sum io.github.frequency403.openssh_gui.desktop | cut -d' ' -f1)
           SHA_LICENSE=$(sha256sum LICENSE | cut -d' ' -f1)
-          
+
           sed -i "s/^pkgver=.*/pkgver=$VERSION/" openssh-gui-bin/PKGBUILD
-          sed -i "s/sha256sums=.*/sha256sums=('$SHA_BIN' '$SHA_ICON' '$SHA_DESKTOP' '$SHA_LICENSE')/" openssh-gui-bin/PKGBUILD
-          
-          # Also update openssh-gui-git pkgver for consistency
+          sed -i "s/^sha256sums=.*/sha256sums=('$SHA_BIN' '$SHA_ICON' '$SHA_DESKTOP' '$SHA_LICENSE')/" openssh-gui-bin/PKGBUILD
           sed -i "s/^pkgver=.*/pkgver=$VERSION/" openssh-gui-git/PKGBUILD
 
       - name: Update AUR (openssh-gui-bin)
@@ -216,4 +215,32 @@ jobs:
           commit_username: ${{ github.repository_owner }}
           commit_email: ${{ github.repository_owner }}@users.noreply.github.com
           ssh_private_key: ${{ secrets.AUR_SSH_PRIVATE_KEY }}
-          commit_message: "Update to ${{ github.ref_name }}"
+          commit_message: "Update to ${{ github.ref_name }}"
+  
+  winget:
+    name: Update Winget Package
+    runs-on: ubuntu-latest
+    needs: release
+    if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/')
+    
+    steps:
+      - name: Extract version from tag
+        id: version
+        run: |
+          VERSION="${GITHUB_REF_NAME#v}"
+          echo "VERSION=$VERSION" >> "$GITHUB_OUTPUT"
+
+      - name: Install Komac
+        run: |
+          curl -sL \
+            "https://github.com/russellbanks/Komac/releases/latest/download/komac-linux-amd64" \
+            -o komac
+          chmod +x komac
+
+      - name: Update Winget manifest
+        run: |
+          ./komac update "frequency403.OpenSSHGUI" \
+            --version "${{ steps.version.outputs.VERSION }}" \
+            --urls "https://github.com/${{ github.repository }}/releases/download/${{ github.ref_name }}/OpenSSH-GUI-win-x64.exe" \
+            --submit \
+            --token "${{ secrets.WINGET_GITHUB_TOKEN }}"

.github/workflows/staging.yml

@@ -76,7 +76,7 @@ jobs:
             -p:PublishSingleFile=true \
             -p:PublishReadyToRun=true \
             -p:IncludeNativeLibrariesForSelfExtract=true \
-            -p:Version="${{ env.VERSION }}"
+            -p:IsNightly=true
 
       - name: Rename artifact
         run: mv ./publish/OpenSSH_GUI${{ matrix.asset_extension }} ./publish/${{ matrix.asset_name }}${{ matrix.asset_extension }}
@@ -121,7 +121,7 @@ jobs:
         with:
           name: OpenSSH-GUI-nightly-x86_64.AppImage
           path: OpenSSH-GUI-nightly-x86_64.AppImage
-          
+
       - name: Upload generated desktop file
         if: matrix.target == 'linux-x64'
         uses: actions/upload-artifact@v4
@@ -140,12 +140,13 @@ jobs:
     name: Create Nightly Release
     runs-on: ubuntu-latest
     needs: build
-
+    
     steps:
       - name: Checkout
         uses: actions/checkout@v4
         with:
           fetch-depth: 0
+          token: ${{ secrets.PAT_TOKEN }}
 
       - name: Resolve git metadata
         run: |
@@ -156,22 +157,34 @@ jobs:
           echo "BUILD_DATE=$DATE"                       >> "$GITHUB_ENV"
           echo "VERSION=${BASE_VERSION}+${HASH}"        >> "$GITHUB_ENV"
 
+      - name: Force-update nightly tag
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git tag -f nightly
+          git push origin -f nightly
+
       - name: Download all build artifacts
         uses: actions/download-artifact@v4
         with:
           path: artifacts/
 
       - name: Display structure of downloaded files
         run: ls -R artifacts
-        
+
+      - name: Collect extra release assets
+        run: |
+          cp OpenSSH_GUI/Assets/appicon.png artifacts/appicon.png
+          cp LICENSE artifacts/LICENSE
+
       - name: Update nightly release
         env:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         run: |
           NOTES="**Branch:** \`development\`
           **Commit:** \`${{ env.GIT_HASH }}\`
           **Built:** ${{ env.BUILD_DATE }}
-  
+          
           > Automated nightly build — not intended for production use."
           
           if gh release view nightly &>/dev/null; then
@@ -185,10 +198,11 @@ jobs:
           
             find artifacts -type f | xargs gh release upload nightly
           else
-            find artifacts -type f | xargs gh release create nightly \
+            gh release create nightly \
               --title "Nightly (${{ env.BUILD_DATE }}) — ${{ env.VERSION }}" \
               --notes "$NOTES" \
-              --prerelease
+              --prerelease \
+              $(find artifacts -type f)
           fi
 
   # --- JOB 3: AUR NIGHTLY ---
@@ -208,7 +222,7 @@ jobs:
         with:
           name: OpenSSH-GUI-nightly-linux-x64
           path: ./
-          
+
       - name: Download generated desktop file
         uses: actions/download-artifact@v4
         with:
@@ -228,7 +242,7 @@ jobs:
           SHA_LICENSE=$(sha256sum LICENSE | cut -d' ' -f1)
 
           sed -i "s/^pkgver=.*/pkgver=$VERSION/" openssh-gui-nightly/PKGBUILD
-          sed -i "s/sha256sums=.*/sha256sums=('$SHA_BIN' '$SHA_ICON' '$SHA_DESKTOP' '$SHA_LICENSE')/" openssh-gui-nightly/PKGBUILD
+          sed -i "s/^sha256sums=.*/sha256sums=('$SHA_BIN' '$SHA_ICON' '$SHA_DESKTOP' '$SHA_LICENSE')/" openssh-gui-nightly/PKGBUILD
 
       - name: Update AUR (openssh-gui-nightly)
         uses: KSXGitHub/github-actions-deploy-aur@v4.1.1

Directory.Build.props

@@ -5,7 +5,8 @@
         <Nullable>enable</Nullable>
         <LangVersion>default</LangVersion>
         <PackageProjectUrl>https://github.com/frequency403/OpenSSH-GUI</PackageProjectUrl>
-        <BaseVersion>3.0.0</BaseVersion>
+        <BaseVersion>3.1.0</BaseVersion>
+        <AvaloniaUseCompiledBindingsByDefault>true</AvaloniaUseCompiledBindingsByDefault>
     </PropertyGroup>
 
     <ItemGroup>

Directory.Build.targets

@@ -22,12 +22,16 @@
             DependsOnTargets="ResolveGitHash">
         <PropertyGroup>
             <BaseVersion Condition="'$(BaseVersion)' == ''">1.0.0</BaseVersion>
+            <IsNightly Condition="'$(IsNightly)' == ''">false</IsNightly>
 
             <IncludeSourceRevisionInInformationalVersion>false</IncludeSourceRevisionInInformationalVersion>
-
             <SourceRevisionId>$(GitCommitHash)</SourceRevisionId>
-            <Version>$(BaseVersion)</Version>
-            <InformationalVersion>$(BaseVersion)+$(GitCommitHash)</InformationalVersion>
+
+            <Version Condition="'$(IsNightly)' != 'true'">$(BaseVersion)</Version>
+            <InformationalVersion Condition="'$(IsNightly)' != 'true'">$(BaseVersion)</InformationalVersion>
+
+            <Version Condition="'$(IsNightly)' == 'true'">$(BaseVersion)-$(GitCommitHash)</Version>
+            <InformationalVersion Condition="'$(IsNightly)' == 'true'">$(BaseVersion)-$(GitCommitHash)</InformationalVersion>
         </PropertyGroup>
     </Target>
 

Directory.Packages.props

@@ -0,0 +1,52 @@
+<Project>
+  <PropertyGroup>
+    <ManagePackageVersionsCentrally>true</ManagePackageVersionsCentrally>
+    <CentralPackageTransitivePinningEnabled>true</CentralPackageTransitivePinningEnabled>
+    <NoWarn>$(NoWarn);NU1507</NoWarn>
+  </PropertyGroup>
+  <ItemGroup>
+    <PackageVersion Include="Avalonia" Version="12.0.4" />
+    <PackageVersion Include="Avalonia.Controls.DataGrid" Version="12.0.0" />
+    <PackageVersion Include="Avalonia.Desktop" Version="12.0.4" />
+    <PackageVersion Include="Avalonia.Fonts.Inter" Version="12.0.4" />
+    <PackageVersion Include="Avalonia.Headless" Version="12.0.4" />
+    <PackageVersion Include="Avalonia.Themes.Fluent" Version="12.0.4" />
+    <PackageVersion Include="AvaloniaUI.DiagnosticsSupport" Version="2.2.2" />
+    <PackageVersion Include="coverlet.collector" Version="10.0.1" />
+    <PackageVersion Include="JetBrains.Annotations" Version="2025.2.4" />
+    <PackageVersion Include="Material.Icons" Version="3.0.2" />
+    <PackageVersion Include="Material.Icons.Avalonia" Version="3.0.2" />
+    <PackageVersion Include="Microsoft.Extensions.Configuration" Version="10.0.9" />
+    <PackageVersion Include="Microsoft.Extensions.Configuration.Binder" Version="10.0.9" />
+    <PackageVersion Include="Microsoft.Extensions.Configuration.FileExtensions" Version="10.0.9" />
+    <PackageVersion Include="Microsoft.Extensions.DependencyInjection" Version="10.0.9" />
+    <PackageVersion Include="Microsoft.Extensions.FileProviders.Embedded" Version="10.0.9" />
+    <PackageVersion Include="Microsoft.Extensions.Hosting" Version="10.0.9" />
+    <PackageVersion Include="Microsoft.Extensions.Logging" Version="10.0.9" />
+    <PackageVersion Include="Microsoft.Extensions.Logging.Abstractions" Version="10.0.9" />
+    <PackageVersion Include="Microsoft.Extensions.Options.DataAnnotations" Version="10.0.9" />
+    <PackageVersion Include="Microsoft.NET.Test.Sdk" Version="18.6.0" />
+    <PackageVersion Include="NSubstitute" Version="5.3.0" />
+    <PackageVersion Include="NSubstitute.Analyzers.CSharp" Version="1.0.17" />
+    <PackageVersion Include="ReactiveUI" Version="23.2.28" />
+    <PackageVersion Include="ReactiveUI.Avalonia" Version="12.0.3" />
+    <PackageVersion Include="ReactiveUI.SourceGenerators" Version="3.1.0" />
+    <PackageVersion Include="ReactiveUI.Validation" Version="7.1.0" />
+    <PackageVersion Include="Serilog.Enrichers.Environment" Version="3.0.1" />
+    <PackageVersion Include="Serilog.Extensions.Hosting" Version="10.0.0" />
+    <PackageVersion Include="Serilog.Sinks.Console" Version="6.1.1" />
+    <PackageVersion Include="Serilog.Sinks.File" Version="7.0.0" />
+    <PackageVersion Include="Shouldly" Version="4.3.0" />
+    <PackageVersion Include="SSH.NET" Version="2025.1.0" />
+    <PackageVersion Include="SshNet.Keygen" Version="2024.2.0.1" />
+    <PackageVersion Include="SshNet.PuttyKeyFile" Version="2024.2.0.3" />
+    <PackageVersion Include="Svg.Controls.Skia.Avalonia" Version="12.0.0.11" />
+    <PackageVersion Include="System.Interactive" Version="7.0.1" />
+    <PackageVersion Include="System.Interactive.Async" Version="7.0.1" />
+    <PackageVersion Include="System.Linq.Async" Version="7.0.1" />
+    <PackageVersion Include="System.Reactive" Version="6.1.0" />
+    <PackageVersion Include="Xaml.Behaviors.Avalonia" Version="12.0.0.1" />
+    <PackageVersion Include="xunit.runner.visualstudio" Version="3.1.5" />
+    <PackageVersion Include="xunit.v3" Version="3.2.2" />
+  </ItemGroup>
+</Project>

OpenSSH_GUI.Core/Configuration/ApplicationConfiguration.cs

@@ -0,0 +1,52 @@
+using System.ComponentModel.DataAnnotations;
+using System.Text.Json.Serialization;
+using Microsoft.Extensions.Options;
+using OpenSSH_GUI.Core.Enums;
+using OpenSSH_GUI.Core.Extensions;
+using Serilog.Events;
+
+namespace OpenSSH_GUI.Core.Configuration;
+
+public class ApplicationConfiguration
+{
+    [JsonIgnore]
+    public static readonly ApplicationConfiguration Default = new()
+    {
+        LookupPaths = [SshConfigFilesExtension.GetBaseSshPath()],
+        PreferredTheme = ThemeVariant.Default,
+        LogLevel = LogEventLevel.Warning,
+        FontSize = 14,
+        LoggerConfiguration = LoggerConfiguration.Default
+    };
+
+    [JsonIgnore]
+    public static string ApplicationConfigurationPath { get; } = Path.Combine(
+        Environment.GetFolderPath(Environment.SpecialFolder.ApplicationData),
+        AppDomain.CurrentDomain.FriendlyName);
+
+    [JsonIgnore]
+    public static string ApplicationConfigurationName { get; } = Path.WithJsonExtension(AppDomain.CurrentDomain.FriendlyName.ToLower());
+
+    [JsonIgnore]
+    public static string DefaultApplicationConfigurationFileFullPath { get; } = Path.Combine(ApplicationConfigurationPath, ApplicationConfigurationName);
+
+    [Required]
+    public required string[] LookupPaths { get; set; }
+
+    [Required]
+    public required ThemeVariant PreferredTheme { get; set; }
+
+    [Required]
+    public required LogEventLevel LogLevel { get; set; }
+
+    [Required, Range(12, 48, ErrorMessage = "Font size must be between 12 and 48")]
+    public required double FontSize { get; set; }
+
+    [Required, ValidateObjectMembers]
+    public required LoggerConfiguration LoggerConfiguration { get; set; }
+}
+
+[JsonSourceGenerationOptions(WriteIndented = true, UseStringEnumConverter = true), JsonSerializable(typeof(ApplicationConfiguration)), JsonSerializable(typeof(LoggerConfiguration))]
+public partial class SourceGenerationContext : JsonSerializerContext
+{
+}

OpenSSH_GUI.Core/Configuration/JsonFileConfigurationWriter.cs

@@ -0,0 +1,53 @@
+using System.Text.Json;
+using System.Text.Json.Serialization.Metadata;
+
+namespace OpenSSH_GUI.Core.Configuration;
+
+public sealed class JsonFileConfigurationWriter<T>(string filePath, JsonTypeInfo<T> typeInfo)
+{
+    private readonly SemaphoreSlim _lock = new(1, 1);
+
+    /// <summary>
+    ///     Reads and deserializes the configuration file into <typeparamref name="T" />.
+    ///     Returns a default instance if the file does not exist.
+    /// </summary>
+    public async Task<T?> ReadAsync(CancellationToken ct)
+    {
+        if (!File.Exists(filePath))
+            return default;
+
+        await using var stream = File.OpenRead(filePath);
+        return await JsonSerializer.DeserializeAsync(stream, typeInfo, ct);
+    }
+
+    /// <summary>
+    ///     Atomically writes <paramref name="value" /> to the configuration file via a temp-file swap.
+    /// </summary>
+    public async Task WriteAsync(T value, CancellationToken ct)
+    {
+        var tempFile = Path.GetTempFileName();
+        await using (var stream = File.Open(tempFile, FileMode.Truncate))
+        {
+            await JsonSerializer.SerializeAsync(stream, value, typeInfo, ct);
+        }
+        File.Move(tempFile, filePath, true);
+    }
+
+    /// <summary>
+    ///     Reads the current configuration, applies <paramref name="update" />, then writes the result back atomically.
+    /// </summary>
+    public async Task UpdateAsync(Func<T?, Task<T>> update, CancellationToken ct)
+    {
+        await _lock.WaitAsync(ct);
+        try
+        {
+            var current = await ReadAsync(ct);
+            var updated = await update(current);
+            await WriteAsync(updated, ct);
+        }
+        finally
+        {
+            _lock.Release();
+        }
+    }
+}