Files
furumi-tui/AGENTS.md
T

11 KiB
Raw Blame History

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:

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:

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.