Files
furumi-tui/AGENTS.md
T

276 lines
11 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# AGENTS.md
This file describes how to work safely in the Furumi repository. It applies to
the entire project.
## Project intent
Furumi is a cross-platform, federated P2P player for personal music libraries.
Every node must remain a complete local player without network access. Other
nodes add discovery, availability, trusted-device synchronization, and direct
track transfer; they are never a prerequisite for using the local library.
Read `ARCHITECTURE.md` before changing federation, device sync, playback
handoff, persistence, or runtime boundaries.
Preserve these architectural invariants:
1. Local import, browsing, playback, playlists, likes, and history work
offline.
2. No central Furumi service becomes required for discovery, playback, or
synchronization.
3. Federation membership does not imply trusted-device membership.
4. Remote state is merged, replicated, or cached locally; it is not treated as
an always-available database.
5. Network, database, filesystem, image, and audio preparation work stays out
of the interactive UI path.
6. Losing peers may reduce remote availability but must not invalidate local
state.
## Toolchain and checks
The crate uses Rust edition 2024 and Rust 1.97 or newer.
Run the checks relevant to every code change:
```bash
cargo fmt --all -- --check
cargo check --all-targets
cargo test --all-targets
cargo clippy --all-targets
```
`cargo clippy --all-targets` currently reports known warnings. Do not hide
them with broad `allow` attributes. Do not claim `-D warnings` passes unless
the existing warning set has actually been resolved.
Use `cargo fmt --all` after editing Rust. Keep `Cargo.lock` committed and
update it only when dependencies change.
## Source boundaries
- `src/main.rs` owns process startup, terminal restoration, Tokio setup, and
platform media-loop integration.
- `src/app/state.rs` owns UI/navigation state.
- `src/app/action.rs` and `src/app/event.rs` define input intent and runtime
results.
- `src/app/update.rs` performs state transitions and requests effects. It must
not perform blocking I/O.
- `src/app/mod.rs` owns runtime orchestration and effect execution.
- `src/library/` owns SQLite library queries, models, imports, and migrations.
- `src/player/` owns rodio playback and audio analysis.
- `src/federation/` owns DHT discovery, peer catalogs, audio exchange, and
federation caches.
- `src/podcasts/` owns podcast feed HTTP and refresh policy, the episode
stream reader (HTTP Range, bounded buffer) and the ordered progress writer;
podcast identity, merge rules and the SQLite store come from FRID
(`music_dht::podcast`, `furumi_library::podcasts`) and must not be
re-derived here. Queue items are identified by `state::track_key` /
`TrackItem::key`, never by numeric id (every episode has the same sentinel
id); music-only code must skip `TrackItem::is_podcast()` items.
- `src/devices.rs` owns trusted-device replication, membership, and playback
coordination. Its wire types are the shared `music_dht::device_sync`
definitions; do not add local copies (golden tests in
`devices/wire_compat_tests.rs` keep the v3 JSON).
- `src/ui/` renders `AppState`; rendering code must not start background work
or mutate persistence.
- `src/media.rs` owns OS media controls.
- `src/visualizer.rs` and `src/visualizations/` own the Rhai visualization
host and bundled scripts.
Prefer adding a focused module when a responsibility has a clear boundary.
Do not split files solely to reduce line count if doing so introduces leaky
APIs or circular ownership.
Keep large test suites in their existing adjacent files:
- `src/app/update_tests.rs`
- `src/devices/tests.rs`
- `src/federation/tests.rs`
- `src/library/tests.rs`
## Application state and concurrency
`AppState` is the single source of truth for the TUI. The normal flow is:
```text
external event -> AppEvent -> Action/update -> Effect -> runtime -> AppEvent
```
Follow these rules:
- Keep update logic deterministic wherever practical.
- Return an `Effect` for work that requires runtime services.
- Report asynchronous results through `AppEvent`.
- Use `tokio::task::spawn_blocking` for blocking SQLite, hashing, tag parsing,
or filesystem-heavy work invoked from async code.
- Do not hold a mutex guard across `.await`.
- Do not call terminal rendering APIs from background tasks.
- Preserve event sequence or request identifiers where they prevent stale
search, download, or synchronization results from overwriting newer state.
## Library and SQLite
`library::Library` is the authority for local catalog persistence. Keep SQL in
the library/device persistence layers rather than spreading it through the UI
or runtime.
When changing schema or stored data:
- provide an upgrade path for existing databases;
- make migrations repeatable and safe on partially upgraded databases;
- preserve foreign-key and uniqueness invariants;
- distinguish durable user data from replaceable federation/cache data;
- test both the new behavior and migration-sensitive queries;
- never solve a schema problem by deleting or recreating a user's database.
Content identifiers are the bridge between independent libraries. Avoid
assuming that local numeric row IDs identify the same track on another node.
## Federation and wire protocols
Discovery and transfer are separate concerns:
- the DHT provides distributed discovery;
- peer catalog streams provide richer metadata;
- audio streams transfer content;
- the device-sync protocol replicates trusted personal state.
Treat protocol and serialized-data changes as compatibility changes:
- preserve existing ALPN values unless intentionally introducing a new
protocol version;
- retain backward-compatible `serde` defaults for fields added to wire types;
- tolerate peers with older or partial metadata;
- bound incoming messages and validate untrusted lengths/identifiers;
- keep catalog/federation authority separate from trusted-device authority;
- assume peers can disappear between discovery and transfer;
- keep retries and fallback sources idempotent.
Do not introduce a required coordinator, registry, account server, or canonical
network database.
## Trusted-device synchronization
Device sync is offline-first. Operations may arrive late, more than once, or
in a different order.
When changing it:
- preserve operation-ID deduplication;
- use the existing hybrid logical time ordering rules consistently;
- ensure deletes survive offline replicas through tombstones;
- compact tombstones only after the required acknowledgements;
- keep snapshots able to repair peers that missed older operations;
- treat membership and revocation as replicated durable state;
- keep playback commands targeted and deduplicated;
- test merge behavior from at least two operation orders;
- never store this build's protocol version for another device: use the
device's own report (`profile_protocol_version`) and only raise a stored
version from relayed profiles (`relayed_protocol_version`);
- gate everything a peer cannot parse by the version it reported: podcast
operations, podcast snapshot sections and playback state with podcast items
go only to v4 peers (`op_allowed_for_peer`, `SyncSnapshot::for_peer`,
`playback_allowed_for_peer`), a podcast queue is never handed to an older
device and its playback commands are ignored while the queue has episodes;
never strip episodes from a queue to make it fit an old peer; an older
peer still gets the playback coordination, with the queue redacted
(`redact_for_jam`), so its engine does not fail over, and the
"Private item" music entries it echoes back in its own states are left
out (`drop_echoed_private_items`), never adopted;
- apply podcast operations and snapshot sections only through
`PodcastStore` (`apply_remote_op`, `apply_snapshot`); never call the
podcast store while holding the sync-log connection;
- keep Jam snapshots redacted (`redact_for_jam`) and map guest placeholders
back with `restore_jam_private_items`.
Do not replace eventual reconciliation with assumptions about a continuously
connected leader.
## Playback and remote resolution
The application owns the logical queue; `player::Controller` owns physical
audio playback.
Remote and local tracks should continue through the same queue and UI model.
When a track is unavailable locally, resolve it asynchronously and replace or
materialize the pending entry without blocking the event loop.
Preserve:
- queue position and prefetch indexes when inserting or removing tracks;
- shuffle/repeat behavior;
- pause and seek state during device handoff;
- fallback to another advertised source when a peer disappears;
- the distinction between cached audio and content imported into the durable
library.
## UI and key bindings
The TUI is keyboard-first and cross-platform.
- Keep rendering pure over `&AppState`.
- Use semantic `Action` values rather than checking raw keys inside views.
- Add default bindings in `src/config/default_keymap.toml`.
- Preserve user overrides and context-specific bindings.
- Tabs are ordered Library, Playlists, Queue, Podcasts, Settings, Logs
(`1`–`6`). `Tab::ALL` defines that order for the tab bar, Tab/Shift+Tab,
and `GoToTab` indices. Changing it, or the meaning of any other
positional action argument, requires a new `KEYMAP_VERSION` and an
in-memory migration of older keymap files; never rewrite the user's file.
- Account for narrow terminals, Unicode display width, and empty/loading/error
states.
- Restore raw mode, alternate screen, bracketed paste, and keyboard
enhancements on exit and panic.
Do not print to stdout/stderr while the alternate-screen UI is active; use
`tracing` and visible application status instead.
## Cross-platform work
Furumi supports Linux, macOS, and Windows.
- Keep OS-specific code behind narrow `cfg` boundaries.
- Do not introduce shell-only behavior into portable paths.
- Use platform data/config/cache directories through the existing config
helpers.
- Consider path encoding, separators, and non-UTF-8 filesystem values.
- Changes to media controls, terminal setup, clipboard behavior, or audio
devices require explicit review of all three platforms.
If only one target can be exercised locally, state which platform-specific
paths remain unverified.
## Tests
Add tests at the closest stable boundary:
- pure state transitions in `app/update_tests.rs`;
- SQLite behavior and migrations in `library/tests.rs`;
- operation merge, tombstone, membership, and playback sync behavior in
`devices/tests.rs`; podcast sync between device stores and simulated v3
peers in `devices/podcast_sync_tests.rs`; wire shapes in
`devices/wire_compat_tests.rs`;
- search/ranking/federation conversion in `federation/tests.rs`;
- protocol-specific tests beside `federation/audio.rs` or
`federation/catalog.rs` when appropriate.
Prefer in-memory SQLite databases and deterministic fixtures. Temporary files
must use unique names and must not depend on a developer's music library,
configuration, home directory, network peers, or audio hardware.
Do not remove a test merely because a refactor makes it inconvenient. Update
it to assert the preserved behavior.
## Documentation and releases
Keep public documentation aligned with the decentralized product model.
README content should explain user value and setup; `ARCHITECTURE.md` should
explain architectural decisions and invariants rather than restating source
code.
Release archives are produced by `.github/workflows/release.yml` and must
include the binary, `README.md`, and `LICENSE`.
The project is licensed under WTFPL version 2.