feat: SQLRunboard initial release (spec #1)

.github/workflows/ci.yml

@@ -0,0 +1,57 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    name: test (${{ matrix.os }}, ${{ matrix.browser }})
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+        browser: [chromium, firefox, webkit]
+    runs-on: ${{ matrix.os }}
+    defaults:
+      run:
+        shell: pwsh
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-dotnet@v5
+        with:
+          global-json-file: global.json
+      - run: dotnet build
+      # Playwright advises against caching the browsers.
+      - run: ./tests/SqlRunboard.Gui.Tests/bin/Debug/net10.0/playwright.ps1 install ${{ matrix.browser }} ${{ runner.os == 'Linux' && '--with-deps' || '' }}
+      - run: dotnet test --no-build
+        env:
+          BROWSER: ${{ matrix.browser }}
+
+  # The integration suite against a real SQL Server, on Linux only (docs/SPEC.md "Tests").
+  # The SA password is a throwaway for this run's container, which only this job can reach.
+  integration:
+    runs-on: ubuntu-latest
+    services:
+      sql:
+        image: mcr.microsoft.com/mssql/server:2022-latest
+        env:
+          ACCEPT_EULA: "Y"
+          MSSQL_SA_PASSWORD: Rb-${{ github.run_id }}-${{ github.run_attempt }}-Sql9
+        ports:
+          - 1433:1433
+        options: >-
+          --health-cmd "/opt/mssql-tools18/bin/sqlcmd -C -b -S localhost -U sa -P $MSSQL_SA_PASSWORD -Q 'SELECT 1'"
+          --health-interval 10s --health-timeout 5s --health-retries 20
+    defaults:
+      run:
+        shell: pwsh
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-dotnet@v5
+        with:
+          global-json-file: global.json
+      - run: dotnet test --project tests/SqlRunboard.Integration.Tests
+        env:
+          SQLRUNBOARD_TEST_SQL: Server=localhost,1433;User ID=sa;Password=Rb-${{ github.run_id }}-${{ github.run_attempt }}-Sql9;TrustServerCertificate=true

.github/workflows/release.yml

@@ -0,0 +1,77 @@
+name: Release
+
+# Push a tag such as v0.1.0 to publish a release.
+on:
+  push:
+    tags: ['v*']
+
+permissions:
+  contents: write
+
+jobs:
+  publish:
+    name: publish (${{ matrix.rid }})
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - { rid: win-x64, os: windows-latest }
+          # macOS runner: the SDK gives the apphost an ad-hoc signature, which Apple silicon needs.
+          - { rid: osx-arm64, os: macos-latest }
+          - { rid: linux-x64, os: ubuntu-latest }
+          - { rid: linux-arm64, os: ubuntu-latest }
+    runs-on: ${{ matrix.os }}
+    defaults:
+      run:
+        shell: pwsh
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-dotnet@v5
+        with:
+          global-json-file: global.json
+      - name: Publish and pack
+        run: |
+          $rid = '${{ matrix.rid }}'
+          $out = "publish/$rid"
+          foreach ($project in 'sqlrunboard', 'sqlrunboard-desktop') {
+            dotnet publish "src/$project" -c Release -r $rid --self-contained `
+              -p:PublishSingleFile=true -p:IncludeNativeLibrariesForSelfExtract=true -p:DebugType=None -o $out
+            if ($LASTEXITCODE) { exit $LASTEXITCODE }
+          }
+          # Pack only the two executables (the win-x64 output also has native .pdb files).
+          $ext = $rid.StartsWith('win') ? '.exe' : ''
+          $files = "sqlrunboard$ext", "sqlrunboard-desktop$ext"
+          $name = "sqlrunboard-${{ github.ref_name }}-$rid"
+          # tar keeps the Unix execute bit. Windows users expect a zip.
+          if ($ext) { Compress-Archive -Path ($files | ForEach-Object { "$out/$_" }) -DestinationPath "$name.zip" }
+          else { tar -czf "$name.tar.gz" -C $out @files }
+          if ($LASTEXITCODE) { exit $LASTEXITCODE }
+      - uses: actions/upload-artifact@v4
+        with:
+          name: ${{ matrix.rid }}
+          path: sqlrunboard-*
+          if-no-files-found: error
+
+  release:
+    needs: publish
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/download-artifact@v5
+        with:
+          path: dist
+          merge-multiple: true
+      - name: Create release
+        shell: pwsh
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          $notes = @'
+          Each archive contains `sqlrunboard` (opens the GUI in your browser) and `sqlrunboard-desktop` (opens the GUI in its own window). The executables are self-contained: you do not need to install .NET.
+
+          The executables are not code signed.
+
+          - macOS: the system quarantines downloaded files. After you extract the archive, run `xattr -d com.apple.quarantine sqlrunboard sqlrunboard-desktop` in the folder.
+          - Windows: SmartScreen can show "Windows protected your PC". Click "More info", then "Run anyway".
+          - Linux: `sqlrunboard-desktop` needs WebKitGTK (for example `libwebkit2gtk-4.1-0`) on the computer.
+          '@
+          gh release create '${{ github.ref_name }}' dist/* --repo '${{ github.repository }}' --title '${{ github.ref_name }}' --notes $notes --generate-notes

Directory.Build.props

@@ -0,0 +1,7 @@
+<Project>
+  <PropertyGroup>
+    <TargetFramework>net10.0</TargetFramework>
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+  </PropertyGroup>
+</Project>

SqlRunboard.slnx

@@ -0,0 +1,12 @@
+<Solution>
+  <Folder Name="/src/">
+    <Project Path="src/sqlrunboard-desktop/sqlrunboard-desktop.csproj" />
+    <Project Path="src/SqlRunboard.Core/SqlRunboard.Core.csproj" />
+    <Project Path="src/SqlRunboard.Gui/SqlRunboard.Gui.csproj" />
+    <Project Path="src/sqlrunboard/sqlrunboard.csproj" />
+  </Folder>
+  <Folder Name="/tests/">
+    <Project Path="tests/SqlRunboard.Core.Tests/SqlRunboard.Core.Tests.csproj" />
+    <Project Path="tests/SqlRunboard.Gui.Tests/SqlRunboard.Gui.Tests.csproj" />
+  </Folder>
+</Solution>

compose.yaml

@@ -0,0 +1,14 @@
+# Local SQL Server for the integration tests (docs/SPEC.md "Tests"). The image is amd64 only:
+# on Apple Silicon, turn on Rosetta in Docker Desktop.
+#   MSSQL_SA_PASSWORD=<strong password> docker compose up -d
+#   SQLRUNBOARD_TEST_SQL="Server=localhost,1433;User ID=sa;Password=<same>;TrustServerCertificate=true"
+#   dotnet test --project tests/SqlRunboard.Integration.Tests
+services:
+  sql:
+    image: mcr.microsoft.com/mssql/server:2022-latest
+    platform: linux/amd64
+    environment:
+      ACCEPT_EULA: "Y"
+      MSSQL_SA_PASSWORD: ${MSSQL_SA_PASSWORD:?set MSSQL_SA_PASSWORD}
+    ports:
+      - "${SQL_PORT:-1433}:1433"

global.json

@@ -0,0 +1,9 @@
+{
+  "sdk": {
+    "version": "10.0.100",
+    "rollForward": "latestFeature"
+  },
+  "test": {
+    "runner": "Microsoft.Testing.Platform"
+  }
+}

src/SqlRunboard.Core/Batch.cs

@@ -0,0 +1,55 @@
+using System.Text.Json.Serialization;
+
+namespace SqlRunboard.Core;
+
+public enum Auth { Integrated, SqlServer, EntraInteractive, EntraDefault }
+
+public enum Encrypt { Mandatory, Optional, Strict }
+
+/// <summary>The target block of the batch file. See docs/SPEC.md "Batch".</summary>
+public sealed record BatchTarget
+{
+    public string? Server { get; init; }
+    public string? Database { get; init; }
+    public Auth Auth { get; init; } = Auth.Integrated;
+    public string? User { get; init; }
+    public string? PasswordVariable { get; init; }
+    public Encrypt Encrypt { get; init; } = Encrypt.Mandatory;
+    public bool TrustServerCertificate { get; init; }
+    public string ExtraConnectionString { get; init; } = "";
+}
+
+/// <summary>The batch settings, with the defaults from docs/SPEC.md "Batch".</summary>
+public sealed record BatchSettings
+{
+    public string? Folder { get; init; }
+    public string Filters { get; init; } = "*.sql";
+    public bool Recurse { get; init; }
+    public int ParallelLimit { get; init; } = 4;
+    public bool StopOnFirstFailure { get; init; }
+    public bool ConfirmBeforeRun { get; init; }
+    public int? TimeoutSeconds { get; init; }
+    public BatchTarget Target { get; init; } = new();
+
+    /// <summary>The ranges of docs/SPEC.md "Batch". JSON input can also give null for the non-null properties.</summary>
+    public bool IsValid => this is { ParallelLimit: >= 1 and <= 64, TimeoutSeconds: null or >= 1, Filters: not null, Target: not null };
+}
+
+/// <summary>
+/// One file of the batch. Path is relative to the folder, with /. Include false: a cleared check box.
+/// State: New or Missing until the next save (docs/SPEC.md "Script order"). The batch file never has it.
+/// </summary>
+public sealed record ScriptEntry(string Path, bool Include, [property: JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)] ScriptState? State = null);
+
+public enum ScriptState { New, Missing }
+
+/// <summary>
+/// One entry in the side list. File is null for an unsaved batch. Scripts is the start order. Run is the current run, or null.
+/// FileError: the app could not read the batch file at the start (for example "File not found"). The entry stays until you remove it.
+/// Version: each change of the batch gets a higher number, so the page can drop a state that is older than the one it has.
+/// </summary>
+public sealed record Batch(int Id, string Name, string? File, bool Dirty, BatchSettings Settings, IReadOnlyList<ScriptEntry> Scripts, RunState? Run = null,
+    [property: JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)] string? FileError = null, long Version = 0);
+
+/// <summary>The move commands of docs/SPEC.md "Script order". One item at a time.</summary>
+public enum MoveTo { Up, Down, Top, Bottom }

src/SqlRunboard.Core/BatchFile.cs

@@ -0,0 +1,43 @@
+using System.Text.Json;
+using System.Text.Json.Serialization;
+
+namespace SqlRunboard.Core;
+
+/// <summary>The file on disk changed after the app loaded or saved it. The user must choose: overwrite it, or load it again.</summary>
+public sealed class BatchFileChangedException(string file) : IOException($"The file changed on disk: {file}");
+
+/// <summary>The batch file, schema version 1. See docs/SPEC.md "Batch". It holds no secrets: the password is never in BatchSettings.</summary>
+public static class BatchFile
+{
+    public const string Extension = ".sqlrunboard.json";
+
+    // A key that is not in the file gets the spec default.
+    sealed record Json(int Version, string? Folder = null, string Filters = "*.sql", bool Recurse = false, int ParallelLimit = 4, bool StopOnFirstFailure = false,
+        bool ConfirmBeforeRun = false, int? TimeoutSeconds = null, BatchTarget? Target = null, IReadOnlyList<ScriptEntry>? Scripts = null);
+
+    static readonly JsonSerializerOptions Options = new(JsonSerializerDefaults.Web) { WriteIndented = true, Converters = { new JsonStringEnumConverter() } };
+
+    public static bool HasExtension(string path) => path.EndsWith(Extension, StringComparison.OrdinalIgnoreCase);
+
+    /// <summary>The batch name: the file name without .sqlrunboard.json.</summary>
+    public static string NameOf(string file) => Path.GetFileName(file)[..^Extension.Length];
+
+    public static string Format(BatchSettings s, IReadOnlyList<ScriptEntry> scripts) =>
+        JsonSerializer.Serialize(new Json(1, s.Folder, s.Filters, s.Recurse, s.ParallelLimit, s.StopOnFirstFailure, s.ConfirmBeforeRun, s.TimeoutSeconds, s.Target, scripts), Options);
+
+    /// <summary>Throws InvalidDataException for an incorrect file.</summary>
+    public static (BatchSettings Settings, IReadOnlyList<ScriptEntry> Scripts) Parse(string text)
+    {
+        Json? j;
+        try { j = JsonSerializer.Deserialize<Json>(text, Options); }
+        catch (JsonException e) { throw new InvalidDataException($"Not a batch file: {e.Message}"); }
+        if (j is not { Version: 1 }) throw new InvalidDataException("Not a batch file of version 1.");
+        var settings = new BatchSettings
+        {
+            Folder = j.Folder, Filters = j.Filters, Recurse = j.Recurse, ParallelLimit = j.ParallelLimit, StopOnFirstFailure = j.StopOnFirstFailure,
+            ConfirmBeforeRun = j.ConfirmBeforeRun, TimeoutSeconds = j.TimeoutSeconds, Target = j.Target ?? new(),
+        };
+        if (!settings.IsValid || j.Scripts?.Any(s => s?.Path is null) == true) throw new InvalidDataException("The batch file has an incorrect setting.");
+        return (settings, [.. (j.Scripts ?? []).Select(s => new ScriptEntry(s.Path, s.Include))]); // a State in the file is not ours
+    }
+}