Libation/AGENTS.md

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 pinned by global.json (10.0.101). 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. Always compile-check a change to the WinForms projects — an earlier version of this file said they could not be built here, and a whole PR's worth of WinForms edits went out unverified on the strength of that.
• 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.