276 lines
11 KiB
Markdown
276 lines
11 KiB
Markdown
# 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.
|