A terminal UI for Libby libbui.vinnymac.dev
libbui AGENTS.md
2.5 kB · 54 lines
Markdown
at main

Working on libbui #

libbui is a terminal UI for a person's own Libby (OverDrive) library account: browse the shelf, search the catalog, borrow, place holds, and download what the library offers for download.

Layout #

Crate Role May depend on
crates/libby Async API client (account + catalog). No UI, no disk. —
crates/libbui-core Config, paths, identity storage, download engine, sidecars. No UI. — (not libby; it talks to the network through traits and plain URLs)
crates/libbui The TUI and the scriptable CLI. both

Hard boundaries #

These are product decisions, not TODOs. Do not work around them.

  1. Be a polite client. Libraries suspend cards that look automated, and the suspension lands on a real person's library card. One account request in flight at a time, a jittered gap between them, no background polling outside the pairing screen, no auto-borrow/auto-return loops. card_suspended stops all traffic for that card.
  2. Nothing prints to the terminal the TUI owns. Logs go to the log file via tracing. print_stdout/print_stderr are denied by lint; the CLI subcommands write through an explicit output handle.

Conventions #

  • Rust 2024, MSRV 1.90, unsafe forbidden. Lints live in [workspace.lints].
  • No unwrap() outside tests. expect("reason") when a failure would be a bug. Test modules start with #![allow(clippy::unwrap_used)] if they want it.
  • Crash loudly rather than guess. No silent fallbacks: an unknown timestamp format or response shape is an error, not a default. Unknown enum values from the server are preserved in an Other(String) variant.
  • Libraries use thiserror enums; only the binary uses color-eyre.
  • Every module opens with a //! doc saying what it owns. Comments explain why, not what.
  • Every user-visible string goes through the Fluent catalog (crates/libbui/locales/<lang>/*.ftl). Never colour alone: pair it with a symbol or a word. Strings from the server are sanitized before rendering.
  • Tests: unit tests inline; HTTP against wiremock; UI through TestBackend and insta snapshots. No test may touch the real network or the user's real config directory.
  • Commits are conventional and lowercase: feat(search): …, fix(core): ….

Commands #

cargo fmt --all
cargo clippy --workspace --all-targets -- -D warnings
cargo test --workspace
INSTA_UPDATE=always cargo test -p libbui   # accept snapshot changes, then review the diff