S9 CI evidence: Contemporary Cellar release hardening

.gitattributes

@@ -0,0 +1 @@
+*.sh text eol=lf

.github/workflows/build-linux.yml

@@ -47,7 +47,27 @@ jobs:
       - name: Unit test
         if: ${{ inputs.run-unit-tests }}
         working-directory: ./Source
-        run: dotnet test
+        env:
+          LIBATION_HEADLESS_CAPTURE_OUTPUT: ${{ inputs.OS == 'Debian' && inputs.architecture == 'x64' && format('{0}/cross-platform-captures/linux-x64', github.workspace) || '' }}
+        run: |
+          shopt -s nullglob
+          TEST_PROJECTS=(_Tests/*.Tests/*.csproj)
+          if (( ${#TEST_PROJECTS[@]} == 0 )); then
+            echo "::error::No unit-test projects were found."
+            exit 1
+          fi
+          for TEST_PROJECT in "${TEST_PROJECTS[@]}"; do
+            dotnet run --project "${TEST_PROJECT}" --configuration Release -- --minimum-expected-tests 1
+          done
+
+      - name: Upload Linux contemporary captures
+        if: ${{ always() && inputs.run-unit-tests && inputs.OS == 'Debian' && inputs.architecture == 'x64' }}
+        uses: actions/upload-artifact@v7
+        with:
+          name: contemporary-captures-linux-x64
+          path: ./cross-platform-captures/linux-x64/*.png
+          if-no-files-found: error
+          retention-days: ${{ inputs.retention-days }}
 
       - name: Publish
         id: publish

.github/workflows/build-mac.yml

@@ -21,6 +21,10 @@ on:
       sign-app:
         type: boolean
         description: "Wheather to sign an notorize the app bundle and dmg."
+      release:
+        type: boolean
+        default: false
+        description: "Whether this artifact is being built for a release."
       architecture:
         type: string
         description: "CPU architecture targeted by the build."
@@ -32,7 +36,7 @@ jobs:
     runs-on: macos-latest
     env:
       RUNTIME_ID: "osx-${{ inputs.architecture }}"
-      WAIT_FOR_NOTARIZE: ${{ vars.WAIT_FOR_NOTARIZE == 'true' }}
+      WAIT_FOR_NOTARIZE: ${{ inputs.release || vars.WAIT_FOR_NOTARIZE == 'true' }}
     steps:    
       - uses: apple-actions/import-codesign-certs@v7
         if: ${{ inputs.sign-app }}
@@ -50,7 +54,16 @@ jobs:
       - name: Unit test
         if: ${{ inputs.run-unit-tests }}
         working-directory: ./Source
-        run: dotnet test
+        run: |
+          shopt -s nullglob
+          TEST_PROJECTS=(_Tests/*.Tests/*.csproj)
+          if (( ${#TEST_PROJECTS[@]} == 0 )); then
+            echo "::error::No unit-test projects were found."
+            exit 1
+          fi
+          for TEST_PROJECT in "${TEST_PROJECTS[@]}"; do
+            dotnet run --project "${TEST_PROJECT}" --configuration Release -- --minimum-expected-tests 1
+          done
 
       - name: Publish
         id: publish
@@ -81,14 +94,15 @@ jobs:
       - name: Notarize bundle
         if: ${{ inputs.sign-app }}
         run: |          
-          if [ ${{ vars.WAIT_FOR_NOTARIZE == 'true' }} ]; then
-            WAIT="--wait"
+          WAIT_ARGS=()
+          if [ "${WAIT_FOR_NOTARIZE}" = "true" ]; then
+            WAIT_ARGS+=(--wait)
           fi
           echo "::debug::Submitting the disk image for notarization"
           # Capture stdout+stderr (2>&1). Use || true so that when notarytool fails (e.g. Apple TOS
           # agreement required), the script does not exit before we can print RESPONSE—otherwise the
           # job would fail with no visible error message in the workflow log.
-          RESPONSE=$(xcrun notarytool submit ./bundle/${{ steps.bundle.outputs.artifact }} $WAIT --no-progress --apple-id ${{ vars.APPLE_DEV_EMAIL }} --password ${{ secrets.APPLE_DEV_PASSWORD }} --team-id ${{ secrets.APPLE_TEAM_ID }} 2>&1) || true
+          RESPONSE=$(xcrun notarytool submit ./bundle/${{ steps.bundle.outputs.artifact }} "${WAIT_ARGS[@]}" --no-progress --apple-id ${{ vars.APPLE_DEV_EMAIL }} --password ${{ secrets.APPLE_DEV_PASSWORD }} --team-id ${{ secrets.APPLE_TEAM_ID }} 2>&1) || true
           echo "$RESPONSE"
           SUBMISSION_ID=$(echo "$RESPONSE" | awk '/id: / { print $2;exit; }')
           echo "::notice::Notary Submission Id: $SUBMISSION_ID"
@@ -100,9 +114,10 @@ jobs:
             exit 1
           fi
 
-          if [ ${{ vars.WAIT_FOR_NOTARIZE == 'true' }} ]; then
+          if [ "${WAIT_FOR_NOTARIZE}" = "true" ]; then
             echo "::debug::Stapling the notarization ticket to the disk image"
             xcrun stapler staple "./bundle/${{ steps.bundle.outputs.artifact }}"
+            xcrun stapler validate "./bundle/${{ steps.bundle.outputs.artifact }}"
           fi
 
       - uses: actions/upload-artifact@v7

.github/workflows/build-windows.yml

@@ -28,6 +28,7 @@ jobs:
     name: "Windows-${{ matrix.release_name }}-${{ matrix.architecture }} (${{ matrix.ui }})"
     runs-on: windows-latest
     strategy:
+      fail-fast: false
       matrix:
         ui: [Avalonia]
         architecture: [x64]
@@ -53,8 +54,25 @@ jobs:
       - name: Unit test
         if: ${{ inputs.run-unit-tests }}
         working-directory: ./Source
-        run: dotnet test
-
+        env:
+          LIBATION_HEADLESS_CAPTURE_OUTPUT: ${{ matrix.ui == 'Avalonia' && matrix.architecture == 'x64' && format('{0}/cross-platform-captures/windows-x64', github.workspace) || '' }}
+        run: |
+          $testProjects = @(Get-ChildItem -Path "_Tests/*.Tests/*.csproj")
+          if ($testProjects.Count -eq 0) { throw "No unit-test projects were found." }
+          foreach ($testProject in $testProjects) {
+            dotnet run --project $testProject.FullName --configuration Release -- --minimum-expected-tests 1
+            if ($LASTEXITCODE -ne 0) { throw "Unit tests failed for $($testProject.FullName)" }
+          }
+
+      - name: Upload Windows contemporary captures
+        if: ${{ always() && inputs.run-unit-tests && matrix.ui == 'Avalonia' && matrix.architecture == 'x64' }}
+        uses: actions/upload-artifact@v7
+        with:
+          name: contemporary-captures-windows-x64
+          path: ./cross-platform-captures/windows-x64/*.png
+          if-no-files-found: error
+          retention-days: ${{ inputs.retention-days }}
+
       - name: Publish
         working-directory: ./Source
         run: |
@@ -66,10 +84,20 @@ jobs:
             "-p:PublishReadyToRun=${{ inputs.publish-r2r }}",
             "-p:SelfContained=true")            
 
-          dotnet publish "Libation${{ matrix.ui }}/Libation${{ matrix.ui }}.csproj" $PUBLISH_ARGS
-          dotnet publish "LoadByOS/WindowsConfigApp/WindowsConfigApp.csproj" $PUBLISH_ARGS
-          dotnet publish "LibationCli/LibationCli.csproj" $PUBLISH_ARGS
-          dotnet publish "Hangover${{ matrix.ui }}/Hangover${{ matrix.ui }}.csproj" $PUBLISH_ARGS
+          # PowerShell does not stop at a native command that fails, and the step is judged by the exit code
+          # of the last one, so a publish that fails anywhere but the end passes as a green build. That is not
+          # hypothetical: LibationWinForms failed to compile for a while and every run stayed green, uploading
+          # a Libation-Classic zip with no Libation.exe in it. Check each one.
+          $projects = @(
+            "Libation${{ matrix.ui }}/Libation${{ matrix.ui }}.csproj",
+            "LoadByOS/WindowsConfigApp/WindowsConfigApp.csproj",
+            "LibationCli/LibationCli.csproj",
+            "Hangover${{ matrix.ui }}/Hangover${{ matrix.ui }}.csproj")
+
+          foreach ($project in $projects) {
+            dotnet publish "$project" $PUBLISH_ARGS
+            if ($LASTEXITCODE -ne 0) { throw "dotnet publish failed for $project" }
+          }
 
       - name: Zip artifact
         id: zip
@@ -81,6 +109,11 @@ jobs:
             "WindowsConfigApp.deps.json")
 
           foreach ($file in $delfiles){ if (test-path $file){ Remove-Item $file } }
+
+          # Both UIs publish as Libation.exe. upload-artifact's if-no-files-found only proves the zip exists,
+          # which it does whether or not the app is inside it, so say outright that it has to be.
+          if (-not (Test-Path "Libation.exe")) { throw "Libation.exe is missing from the publish output" }
+
           $artifact="${{ matrix.artifact_stem }}.${{ inputs.libation-version }}-windows-${{ matrix.release_name }}-${{ matrix.architecture }}.zip"
           "artifact=$artifact" >> $env:GITHUB_OUTPUT
           Compress-Archive -Path * -DestinationPath "$artifact"
@@ -127,4 +160,3 @@ jobs:
           path: ./bin/${{ steps.setup.outputs.setup }}
           if-no-files-found: error
           retention-days: ${{ inputs.retention-days }}
-

.github/workflows/build.yml

@@ -40,6 +40,7 @@ jobs:
 
   macOS:
     strategy:
+      fail-fast: false
       matrix:
         architecture: [x64, arm64]
     uses: ./.github/workflows/build-mac.yml
@@ -51,10 +52,12 @@ jobs:
       retention-days: ${{ inputs.retention-days }}
       architecture: ${{ matrix.architecture }}
       sign-app: ${{ inputs.release || vars.SIGN_MAC_APP_ON_VALIDATE == 'true' }}
+      release: ${{ inputs.release }}
     secrets: inherit
 
   linux:
     strategy:
+      fail-fast: false
       matrix:
         OS: [Redhat, Debian]
         architecture: [x64, arm64]
@@ -68,5 +71,3 @@ jobs:
       architecture: ${{ matrix.architecture }}
       OS: ${{ matrix.OS }}
 
-
-

.github/workflows/docker.yml

@@ -36,7 +36,7 @@ jobs:
 
       - name: Login to Docker Hub
         if: ${{ inputs.release }}
-        uses: docker/login-action@v4.5.2
+        uses: docker/login-action@v4.6.0
         with:
           username: ${{ secrets.docker_username }}
           password: ${{ secrets.docker_token }}
@@ -59,7 +59,9 @@ jobs:
           context: .
           platforms: linux/amd64,linux/arm64
           push: ${{ steps.metadata.outputs.tags != ''}}
+          # Always read cache. Only write on release so PR validate cannot fail
+          # when GHA cache is full or the token cannot write cache.
           cache-from: type=gha
-          cache-to: type=gha,mode=max
+          cache-to: ${{ inputs.release && 'type=gha,mode=max,ignore-error=true' || '' }}
           tags: ${{ steps.metadata.outputs.tags }}
           labels: ${{ steps.metadata.outputs.labels }}

.github/workflows/release.yml

@@ -36,6 +36,7 @@ jobs:
       libation-version: ${{ needs.prerelease.outputs.version }}
       publish-r2r: true
       release: true
+      run-unit-tests: true
 
   release:
     needs: [prerelease, build]

.github/workflows/validate.yml

@@ -8,11 +8,13 @@ on:
     branches: [master]
     paths:
       - Source/**
+      - Scripts/**
       - .github/workflows/**
   pull_request:
     branches: [master]
     paths:
       - Source/**
+      - Scripts/**
       - .github/workflows/**
 
 jobs:

.vitepress/config.js

@@ -94,7 +94,19 @@ export default defineConfig({
             text: "Audiobookshelf Auto-Upload",
             link: "/docs/features/audiobookshelf",
           },
+          {
+            text: "Daily Download Limit",
+            link: "/docs/features/daily-download-limit",
+          },
           { text: "Naming Templates", link: "/docs/features/naming-templates" },
+          {
+            text: "Parallel Downloads",
+            link: "/docs/features/parallel-downloads",
+          },
+          {
+            text: "Retrying Refused Downloads",
+            link: "/docs/features/retrying-refused-downloads",
+          },
           {
             text: "Searching & Filtering",
             link: "/docs/features/searching-and-filtering",
@@ -103,6 +115,7 @@ export default defineConfig({
             text: "Easy guide to searching",
             link: "/docs/features/lucene",
           },
+          { text: "Trash Bin", link: "/docs/features/trash-bin" },
         ],
       },
       {
@@ -124,6 +137,7 @@ export default defineConfig({
             link: "/docs/development/getting-started",
           },
           { text: "Contribute", link: "/docs/development/contribute" },
+          { text: "Testing Changes", link: "/docs/development/testing" },
           { text: "Website & Docs", link: "/docs/development/website" },
           { text: "Linux Setup (Nix)", link: "/docs/development/nix-linux-setup" },
         ],

AGENTS.md

@@ -0,0 +1,75 @@
+# AGENTS.md
+
+## Cursor Cloud specific instructions
+
+Libation is a cross-platform .NET desktop/CLI app for downloading and de-DRMing Audible
+audiobooks. The core product is the Avalonia GUI (`LibationAvalonia`, assembly name `Libation`)
+plus a headless CLI (`LibationCli`) that shares the same config and SQLite library database.
+
+### Toolchain / environment
+- Requires the **.NET 10 SDK**. `global.json` sets a `10.0.101` floor with `rollForward: latestFeature`,
+  so any newer 10.0.x SDK is used as-is. It is preinstalled at
+  `~/.dotnet`; `~/.bashrc` exports `DOTNET_ROOT` and adds `~/.dotnet` (and `~/.dotnet/tools`) to
+  `PATH`. New non-login shells may not have it — use `dotnet` after a login shell, or call
+  `~/.dotnet/dotnet` directly.
+- The startup update script runs `dotnet tool restore` (restores `dotnet-ef`) and
+  `dotnet restore Source/Libation.slnx`. No other setup is needed.
+- The solution file is the new XML format: `Source/Libation.slnx` (there is no classic `.sln`).
+
+### Building — everything compiles on Linux, only some of it runs
+- `dotnet build Source/Libation.slnx` succeeds on Linux with 0 errors. So do
+  `LibationWinForms`, `HangoverWinForms` and the `LoadByOS/{Windows,MacOS}ConfigApp` helpers,
+  individually: they target `net10.0-windows7.0` but set `EnableWindowsTargeting`, which is what makes
+  a non-Windows SDK build them. Compile-check every change to the WinForms projects here; a Linux
+  build is the only automated check those projects get before a human on Windows sees them.
+- Compiling is not running. WinForms has no Linux runtime, so behaviour and layout in
+  `LibationWinForms` / `HangoverWinForms` still need a human on Windows. Say so explicitly rather than
+  implying a WinForms change was tested.
+- Build the runnable cross-platform apps directly:
+  - `dotnet build Source/LibationAvalonia/LibationAvalonia.csproj`
+  - `dotnet build Source/LibationCli/LibationCli.csproj`
+- There is no dedicated lint step; the repo's `.editorconfig` is minimal and CI
+  (`.github/workflows/validate.yml`) only builds and tests. The compiler/analyzer warnings from a
+  normal build serve as the static-analysis check. (A known transitive `NU1903` SQLite
+  vulnerability warning is expected and harmless.)
+
+### Testing
+- Test projects live under `Source/_Tests/` and use MSTest on **Microsoft.Testing.Platform**
+  (configured via `global.json` `test.runner`). Because of this runner, `dotnet test` requires
+  `--project` for a single project (a positional project path is rejected):
+  `dotnet test --project Source/_Tests/FileManager.Tests/FileManager.Tests.csproj`
+- CI runs `dotnet test` from `Source/` on every platform, Linux included, and it works here too: the
+  restore covers the whole solution but only the test projects and their references are compiled, so
+  the Windows-only projects never break the run. Naming one project is simply quicker.
+- **Manual UI testing:** `dotnet run Scripts/seed-demo-library.cs` fills the library with fake books
+  covering every Liberate-column icon and prints the expected result for each row
+  (`-- --clean` removes them). Read `docs/development/testing.md` before seeding library state by
+  hand: the yellow lamp is an `.aaxc` file on disk rather than a stored status, `AudioExists` is a
+  database check so green/error need no files, and a podcast's series is keyed off the parent
+  book's own ASIN or the grid silently drops the parent row.
+- **GNOME Keyring / OS secret store:** Libation's default `TokenStorageMethod` is `Encrypted`,
+ and the AES-GCM master key is stored via the OS secret store (`OsSecretStore` /
+ `IdentityTokenStorageWiring`). On Linux that is GNOME Keyring (Secret Service), which **blocks
+ indefinitely** here: the login keyring is locked with a password nobody has, and the D-Bus call
+ hangs even with no prompt on screen. Probing availability does not help - the probe is the
+ blocking call.
+ Every test project should finish in about a second. If one runs for minutes, assume something
+ reached the OS secret store; do not sit through it and do not re-run it hoping for a different
+ result. `ResolveSecretStore` short-circuits on `LIBATION_MASTER_KEY_FILE`, an existing
+ `libation-master.key` under the Libation files dir, or `LIBATION_MASTER_KEY`, so setting one of
+ those keeps a test off the OS store entirely.
+ The tests that deliberately exercise the real store are opt-in via
+ `LIBATION_TEST_OS_SECRET_STORE=1` and are skipped otherwise. Leave them skipped on Linux; they
+ will hang if enabled. Always run tests under `timeout` so a regression here cannot stall a session.
+
+### Running the apps
+- GUI: a display is available on `DISPLAY=:1`. Run with
+  `cd Source/LibationAvalonia && dotnet run`. First launch shows a Welcome/walkthrough and creates
+  config under `~/.local/share/Libation/` (`Settings.json`, `AccountsSettings.json`,
+  `LibationContext.db`). The same keyring note above applies when the GUI/CLI first encrypts
+  account tokens.
+- CLI: `cd Source/LibationCli && dotnet run -- <command>` (e.g. `version`, `get-setting`,
+  `list-accounts`, `scan`, `liberate`). The CLI reads the same `~/.local/share/Libation/` config
+  and database as the GUI.
+- Actually scanning/downloading a library requires signing into a real Audible account, so full
+  end-to-end liberation cannot be exercised without credentials.

Directory.Build.props

@@ -2,4 +2,12 @@
   <PropertyGroup>
     <EnableMSTestRunner>true</EnableMSTestRunner>
   </PropertyGroup>
+
+  <ItemGroup>
+    <!-- The SDK supplies Microsoft.SourceLink.Common and the git tasks, which is enough to find the
+         repository but not to turn its URL into fetchable source URLs. Without a host provider every
+         project warns that the generated source link is empty and ships PDBs that cannot locate their
+         sources. -->
+    <PackageReference Include="Microsoft.SourceLink.GitHub" Version="10.0.301" PrivateAssets="All" />
+  </ItemGroup>
 </Project>