Fixed build. Reworked mobile admin UI
Build and Publish / Build and Publish Docker Image (push) Successful in 7m46s

This commit is contained in:
Aleksandr Bogomiakov committed 2026-11-18 15:17:50 +00:00
1 parent 939fc00e4c
commit 9b923851ae
17 files changed
+3095 -2537

No files matched your search

Generated
+1 -1
View File
@@ -1988,7 +1988,7 @@ checksum = "e6d5a32815ae3f33302d95fdcb2ce17862f8c65363dcfd29360480ba1001fc9c"
[[package]]
name = "furumusic"
version = "0.12.3"
version = "0.12.4"
dependencies = [
"anyhow",
"async-stream",
+6
View File
@@ -4,6 +4,12 @@ version = "0.12.4"
edition = "2024"
description = "Reusable web-app boilerplate: auth, OIDC/SSO, admin panel, user management, i18n, PostgreSQL"
# Unoptimized dependencies overflow macOS compact unwind's 24-bit DWARF offset
# (16 MiB of __eh_frame). Keep dependency code small while leaving application
# code unoptimized and retaining debug symbols, assertions and panic unwinding.
[profile.dev.package."*"]
opt-level = 1
# macOS 27 rejects some stripped proc-macro dylibs with a misaligned LINKEDIT
# string pool. Build scripts and proc macros are compile-time artifacts only.
[profile.release.build-override]
+35 -296
View File
@@ -2,313 +2,52 @@
**Your library. Your users. Your network.**
Furumusic is a self-hosted, multi-user music server with a full web player and
support for the Furumi federated network. It turns a collection of music files
into a shared library that is available from any modern browser, while every
user keeps their own playlists, likes, listening history, and playback state.
Furumusic is a self-hosted music server with a full web player. Bring your music,
share a library with friends, and keep your own playlists, likes, and listening
history. Listen from a desktop or phone, or connect independent servers through
the Furumi federated network.
Music can be uploaded directly, imported from a `.torrent` file, or downloaded
from a magnet link. An optional AI-assisted import pipeline reads the available
tags and path information, reconstructs inconsistent metadata, finds artwork,
and organizes the result into artists, releases, and tracks. Uncertain matches
are kept for review instead of silently entering the library with bad data.
## What you can do
## Why Furumusic?
- **Listen anywhere.** Browse artists and releases, search your collection, build
queues, and manage playlists in a responsive web player.
- **Bring your collection.** Upload files and folders, or import music from
YouTube, torrents, and magnet links directly into your library or a playlist.
- **Organize your music.** Optional AI assistance recognizes metadata, finds
artwork, and helps repair messy releases. Review proposed changes before
applying them.
- **Share a song.** Send a track or queue link that anyone can play and download
without creating an account.
- **Welcome your people.** Use password login or SSO. Instance admins can approve
new users without needing access to the identity provider.
- **Discover more.** Find similar tracks and connect Last.fm for scrobbling.
- **Connect your players.** Pair trusted Furumi devices to synchronize playlists,
likes, playback state, and playback controls.
- **Join a network.** Discover and stream music from other participating peers
while keeping your own library independent.
- **Manage from any screen.** Review imports, manage users and background tasks,
and explore listening statistics in a desktop and mobile admin console.
Furumusic is for a household, a small community, or anyone who wants one music
library without handing it to a subscription service. The server owns the
catalog and media files; the browser is only the player.
AI assistance, federation, similarity search, Last.fm, and SSO are optional.
You choose which features to enable.
- one shared library with separate user accounts;
- a responsive web player with artists, releases, search, queue, and playlists;
- direct file uploads and imports from YouTube, torrent files, or magnet links;
- optional AI-assisted recognition and normalization of metadata;
- password login or OIDC/SSO with group grants and local administrator approval;
- public track, release, and queue links with scoped guest playback and downloads;
- optional federation without a central catalog or search service;
- trusted-device pairing, playback handoff, and synchronization between Furumi
players;
- Last.fm scrobbling and similarity-based discovery when configured.
## Quick start
Furumusic does not include music. Import only media you are allowed to store and
share.
## Access and public sharing
OIDC identifies accounts by issuer and subject. Matching admin groups take
precedence over matching user groups, and either SSO grant takes precedence over
a local role. Without matching groups (including an empty group configuration),
a new account waits for approval in **Admin → Users**. Any instance administrator
can approve it as a user or administrator. The waiting page updates automatically.
On subsequent SSO logins the group grant is refreshed: if it disappears, only an
independently assigned local role preserves access. Existing password accounts
keep their local roles; existing OIDC-only accounts retain their last SSO grant
until the next login, without receiving an implicit local approval.
Sharing creates an unguessable `/share/{token}` link to a snapshot of track IDs,
including their order and repetitions. Guests and accounts awaiting approval can
play and download only the tracks in that snapshot, using the regular player.
They cannot browse the library, search, use recommendations, or write personal
history. Signing in from a share returns to that share; signing in from the root
shows only the approval page until access is granted. Track info offers a browser
download of the original audio file. The old radio implementation is removed.
Migration `m_0053_local_approval_and_public_shares` deletes the old share records.
Old track/release/playlist URL routes are removed, with no compatibility layer.
Link expiry, cleanup, and revocation are not part of this implementation.
The access regression suite uses a disposable migrated database and a local OIDC
provider with signed tokens and PKCE:
```bash
node --test tests/*.test.cjs
FURU_ACCESS_TEST_DATABASE_URL=postgresql://... cargo test postgres_approval_survives_sso_changes_without_implicit_grants -- --ignored
# Fresh disposable instance on :18048, media root /tmp/furumi-access-media,
# PostgreSQL container furumi-access-test-pg, database furumi_access_test:
node tests/browser-access-sharing.cjs
```
The browser test requires Playwright (`PLAYWRIGHT_MODULE`) and Chrome
(`CHROME_PATH`), and uses local port 18049 for its OIDC provider. It checks
approval, SSO precedence and group removal, guest playback and downloads,
unauthorized track substitution, and desktop/mobile player behavior.
## Importing music
Users can add audio files from the web interface or ask the server to download
selected files from a torrent. Both routes feed the same import pipeline, so a
library remains consistent regardless of where its files came from.
The importer combines embedded tags, filenames, folder structure, and existing
catalog context. With an OpenAI-compatible language model configured, it can
normalize artist and release names, separate featured artists, recover track
numbers and release types, and flag ambiguous results for a user to approve.
Cover art is taken from nearby image files or embedded artwork when available.
The inbox and permanent library are separate directories. New files are first
processed in the inbox and are moved into the organized library only after
their metadata has been accepted.
## Federation
Federation is optional. Independent Furumusic and Furumi players that use the
same Network ID discover one another as a logical network. Each peer keeps its
own library and can continue working alone.
When federation is enabled, local and remote artists, releases, and tracks can
appear in the same search and library views. Missing audio is streamed from an
available peer and can optionally be retained locally. Similarity search also
stays decentralized: embeddings and exact ranking remain on the instance that
owns the music.
Trusted-device pairing is separate from public catalog discovery. It connects
a user's own Furumi players so likes, playlists, playback state, and control can
move between approved devices.
## Build and run
Furumusic requires PostgreSQL and a Rust toolchain with Rust 2024 edition
support. Create an empty database, provide its connection URL, and start the
server:
With Rust and PostgreSQL installed, create an empty database and start the server:
```bash
export FURU_DATABASE_URL='postgresql://furumusic:password@127.0.0.1/furumusic'
cargo run --release --locked
```
Open <http://127.0.0.1:8000/admin/setup> to create the first administrator.
After setup, configure the inbox and library directories under **Admin →
Settings** before importing music.
Open <http://127.0.0.1:8000/admin/setup> to create your administrator account,
then configure the inbox and music library directories in **Admin → Settings**.
To listen on another address or port:
## Documentation
```bash
cargo run --release --locked -- -l 0.0.0.0:8000
```
- [Installation and configuration](docs/setup.md)
- [Using and administering Furumusic](docs/administration.md)
- [Development, architecture, and tests](docs/development.md)
- [Admin UI conventions](docs/admin-ui.md)
A Nix development shell is included for Linux and macOS:
```bash
nix develop
cargo run --locked
```
The repository also contains a multi-stage `Dockerfile` for building a small
runtime image. A deployment must provide PostgreSQL plus persistent, writable
volumes for the inbox and music library.
CI uses Rust 1.97.0 and cargo-chef 0.1.74 to cache compiled dependencies separately
from application sources. Buildx imports and exports intermediate layers through
`ultradesu/furumusic:buildcache` (`mode=max`). After the first build, changes to
source code, templates or prompts reuse the dependency layer when its recipe and
toolchain are unchanged. Both dependency and application builds use `--locked`.
Update the pinned build tools in `Dockerfile`; changing them rebuilds the cache.
## Admin statistics
The only admin interface is `/admin/v2`, also reachable from `/admin/`.
**Statistics** shows listening totals, a timeline, artist/track/release rankings,
and paginated history. Select an artist or track to see its listeners, then a
listener to see their history within the same filters. The **Users** list links
to each user's full statistics.
Periods use UTC. Counts come from the synchronized `listen_event` history: a
natural finish, half of a track, or four minutes qualifies as a play. Interrupted
sessions under five seconds are not retained. Short retained sessions contribute
to listened time but not play counts. The source filter separates this instance
from synchronized devices. Artist rankings use recorded artist names, including
featured credits; the same artist is counted once per event. Existing history
remains available when its local audio file is deleted. Library and service
cards show current instance totals, independently of the listening filters.
Migration `m_0051_add_listen_statistics_indexes` adds time and content indexes.
The old admin pages and `/admin/debug` are removed; first-run setup remains at
`/admin/setup`.
Regression checks:
```bash
node --test tests/*.test.cjs
cargo test admin:: -- --skip postgres_statistics_drilldown_and_pagination
# Use a disposable PostgreSQL; this test creates connection-local temporary tables.
FURU_STATISTICS_TEST_DATABASE_URL=postgresql://... cargo test postgres_statistics_drilldown_and_pagination -- --ignored
```
`tests/browser-statistics.cjs` additionally exercises a fresh disposable instance
at `FURU_TEST_URL` (default `http://127.0.0.1:3018`) and seeds the disposable Docker
container `furumi-statistics-test-pg`. It requires Playwright (or
`PLAYWRIGHT_MODULE`) and Chrome (or `CHROME_PATH`). Never point this test at a
live service.
## Metadata Repair
Admin → Library Tools provides a chat for editing the selected library resources.
Use **Show related**, then **Deselect all** to choose only the resources needed
for the task. Selecting a release includes its tracks; individual tracks can
then be unchecked to exclude them. Unselected artists remain read-only context
and their IDs can still be used in credits. Releases show their years; tracks
show their source release.
The assistant sees the complete selected scope and replaces the proposed plan
after every clarification. Expand **Proposed changes** in the chat to review or
edit it before applying. Plans support moving tracks, creating releases, merging
releases, and deleting artists, releases, or tracks. Release deletion requires
explicit moves or deletion of all its tracks. Artist deletion detaches credits
and requires all credited releases and tracks to be included.
Applied plans are transactional and can be undone from History. Metadata Repair
retains audio and artwork files for Undo. Undo refuses to overwrite subsequent
metadata, playback, or federation changes.
```bash
node --test tests/admin_metadata_repair.test.cjs
cargo test admin::metadata_fix::tests
```
`tests/browser-metadata-repair.cjs` checks the chat and plan updates, a four-release
merge, deletion and restoration of tracks and artist credits, playlists, playback
queues, and undo conflicts. Run it only against a disposable instance and a
PostgreSQL container named `furumi-repair-test-pg`, with database
`furumi_repair_test`. Set `FURU_TEST_URL`, `FURU_REPAIR_TEST_PG`, `CHROME_PATH`, and
`PLAYWRIGHT_MODULE` as needed. It seeds `tests/metadata_repair_fixture.sql` after
creating the test administrator. Set `FURU_REPAIR_SKIP_SEED=1` for a seeded database.
With `FURU_REPAIR_TEST_MODEL=1`, it additionally checks the reported release-only
selection and full ordered tracklist against the configured model, applies and
undoes that plan, and verifies individual track exclusions.
## Importing into playlists
The player's download manager offers **Add downloads to a playlist** for file
and folder uploads and torrents, as well as YouTube. Choose an existing owned
playlist or create one before starting; leaving the choice empty imports only
into the library. Selected audio tracks are appended after processing or manual
approval, including files resolved to tracks already in the library.
Migration `m_0052_add_import_playlist_destinations` persists the destination and
completion receipts. Retries and restarts retain the choice, avoid duplicates,
and do not re-add tracks subsequently removed by the user. A started batch keeps
its destination for its remaining files.
```bash
node --test tests/import_playlists.test.cjs
# Disposable PostgreSQL; both tests use temporary tables.
FURU_IMPORT_TEST_DATABASE_URL=postgresql://... cargo test import_destinations -- --ignored
FURU_IMPORT_TEST_DATABASE_URL=postgresql://... cargo test torrent_playlist -- --ignored
```
`tests/browser-import-playlists.cjs` checks the file upload flow, database
reconciliation and the torrent picker on desktop and mobile. It requires a fresh
migrated instance with the import agent disabled at `FURU_TEST_URL` (default
`http://127.0.0.1:3019`), the disposable PostgreSQL container
`furumi-import-playlist-test-pg` with database `furumi_import_test`, and Playwright
and Chrome configured as above. It uses a local torrent preview fixture and
simulated imported tracks, without downloading external torrents.
## Configuration
Most settings can be changed from the administration interface. Every setting
also has a `FURU_`-prefixed environment variable; environment values take
priority over values stored in PostgreSQL.
The settings needed for a useful first installation are:
| Setting | Purpose |
| --- | --- |
| `FURU_DATABASE_URL` | PostgreSQL connection URL; required to run the service |
| `FURU_AGENT_INBOX_DIR` | Temporary inbox for uploads and downloaded files |
| `FURU_AGENT_STORAGE_DIR` | Permanent, organized music library |
| `FURU_AGENT_ENABLED` | Enables the background metadata import pipeline |
| `FURU_AGENT_LLM_URL` | Base URL of an OpenAI-compatible model server |
| `FURU_AGENT_LLM_MODEL` | Model used to recognize and normalize metadata |
| `FURU_FEDERATION_ENABLED` | Publishes the library and enables peer discovery |
| `FURU_FEDERATION_NETWORK_ID` | Joins peers with the same value into one logical network |
AI recognition, federation, similarity search, Last.fm, and OIDC are optional.
A local password-authenticated server can be used without any of them.
## Architecture
Furumusic is written in Rust on the
[Cot](https://cot.rs) web framework. PostgreSQL stores the catalog, accounts,
playlists, configuration, and background-job state. Audio inspection uses
Symphonia, torrent downloads use librqbit, and the shared `music-dht`/Frid
protocol stack provides decentralized catalog search, media transfer, and
connected-device synchronization.
The browser interface and JSON API are served by the same application. Import,
artwork, metadata enrichment, similarity indexing, and maintenance run as
durable background jobs rather than blocking playback requests.
The `lastfm_popularity` job defaults to **light** mode: it requests popularity
only for tracks without a completed lookup or with a changed title or primary
artist. Both matches (including zero counts) and explicit Last.fm “Track not
found” results are skipped on subsequent light runs. HTTP errors, timeouts,
invalid responses, and other API errors remain eligible for retry. A failed
full refresh also makes that track eligible for the next light run.
Choose **Full: refresh all visible tracks** in the task's admin parameters to
refresh existing statistics and retry previous misses. The options endpoint
`POST /admin/v2/api/jobs/lastfm_popularity/run-options` accepts
`{"refresh_existing": true}`; an empty object, scheduled runs, and the ordinary
run endpoint use light mode. Neither mode limits the number of tracks processed.
An authoritative miss clears current statistics while preserving their history.
The migration preserves existing popularity; legacy misses need one more lookup
because older versions did not persist them.
## Contributing
Bug reports, design discussions, and patches are welcome. Before submitting a
change, run:
```bash
cargo fmt --all -- --check
cargo clippy --all-targets -- -D warnings
cargo test --all-targets
```
Last.fm database tests use temporary tables on a disposable PostgreSQL database:
```bash
FURUMUSIC_LASTFM_TEST_DATABASE_URL=postgres://user:pass@localhost/test_db \
cargo test lastfm_popularity -- --include-ignored
```
Bug reports, ideas, and contributions are welcome.
+100
View File
@@ -0,0 +1,100 @@
# Admin interface conventions
[Project overview](../README.md) · [Development](development.md)
The admin UI uses one Alpine application and shared layout primitives for every
section. Add features to this model rather than introducing a separate mobile
page or section-specific navigation.
## Ownership
- `templates/admin/navigation.html`: the single navigation tree, grouped into
Operations (reviews/tasks), Music (library/tools/statistics), and Instance
(users/settings). Existing hash routes remain the source of navigation state.
- `templates/admin/styles.html`: colors, typography and component appearance.
- `templates/admin/responsive.html`: shared layout, breakpoints, touch targets,
scroll regions, table cards and dialog sizing. Put responsive rules here.
- `templates/admin/ui.html`: viewport state, task tabs, settings navigation and
the shared overlay lifecycle. Business data and API actions remain in
`adminV2()` in `v2.html`.
## Layout
| Width | Navigation | Workspaces | Lists and dialogs |
| --- | --- | --- | --- |
| 1280 px and above | Persistent sidebar | Task list/detail/log side by side | Tables, centered bounded dialogs |
| 1024–1279 px | Persistent sidebar | Task tabs; settings in one column | Tables, bounded dialogs |
| 768–1023 px | Drawer | Task tabs; settings section picker | Tables in contained scroll areas |
| Below 768 px | Drawer | Single column | Table cards, full viewport dialogs |
Keep CSS and `matchMedia` breakpoints in `ui.html` synchronized. The main panel
owns page scrolling. Use `minmax(0, 1fr)` and `min-width:0` for grid/flex children;
never restore a global minimum page width. The top bar stays available while
content scrolls. Navigation closes after route changes and when switching to
the desktop layout. It retains the active section and the existing URL routes.
Use `.panel`, `.panel-head`, `.panel-title`, `.toolbar`, `.action-strip`, `.field`
and `.editor-grid` for new content. Toolbars wrap, inputs fill available space,
and mobile controls use 44 px touch targets and 16 px input text. Long identifiers,
paths and names must wrap. Avoid fixed column widths and inline grid definitions.
For tabular lists, add `.responsive-table`, a `data-label` to every cell, and
`data-primary` to its identifying cell. Mobile CSS presents the same DOM as cards;
do not duplicate rows or hide actions. Give clickable row titles real buttons
using `.row-link`, so the operation also works with a keyboard. Dense comparisons,
charts and logs may scroll inside a named, keyboard-focusable region; horizontal
scrolling must never propagate to the page. Keep these exceptions intentional.
Task tabs change presentation only: configuration and selected run stay in memory
when switching tabs or rotating the device. In settings, add a section ID and a
matching entry to the section picker. Put related controls in `.settings-grid`.
## Dialogs
Every dialog uses the same hierarchy and lifecycle:
```html
<div class="modal-backdrop" x-show="exampleOpen"
x-effect="adminOverlay.sync($el, !!exampleOpen)"
@keydown="adminOverlay.keydown($event, $el)"
@click.self="closeExample()">
<section class="modal" role="dialog" aria-modal="true"
aria-labelledby="example-title" tabindex="-1">
<div class="modal-head">
<strong id="example-title">Edit item</strong>
<button class="icon-btn" data-dialog-close
aria-label="Close dialog" @click="closeExample()">…</button>
</div>
<form class="modal-body" @submit.prevent="saveExample()">
<!-- .field and .editor-grid -->
<div class="dialog-actions"><button type="submit" class="btn primary">Save</button></div>
</form>
</section>
</div>
```
The helper locks the background with `inert`, moves focus into the dialog, traps
Tab/Shift+Tab, handles Escape through the existing close button, and restores
focus on close. Keep business rules in the close handler and disable that button
when closing is not allowed (for example, while merging). Nested pickers consume
Escape with `.stop` before the dialog handles it. Headers remain fixed while the
body scrolls; `.dialog-actions` keeps actions available at the bottom. On mobile,
dialogs use `100dvh` and safe-area padding. Reuse the helper for new overlays.
For content gated by an asynchronous load inside an animated dialog, use
`:hidden="loading"` instead of nesting competing `x-show` transitions. Loading
and content should not both stay hidden when a response arrives during opening.
## Verification
Run `node --test tests/*.test.cjs` and build the Rust application (templates are
compiled into the binary). `tests/browser-admin-responsive.cjs` checks all seven
sections at 320, 390, 768, 1024 and 1440 px, navigation focus, task state retention,
settings jumps, all five dialogs, long content and landscape geometry. It uses a
disposable running instance with an admin and at least one release containing a
track; browser fixtures do not modify server data. Supply `FURU_TEST_URL`,
`FURU_TEST_USERNAME`, `FURU_TEST_PASSWORD`, `PLAYWRIGHT_MODULE`, and `CHROME_PATH`
as appropriate. Set `FURU_TEST_SCREENSHOTS` to inspect screenshots visually.
Check both populated and empty views, long names/paths, loading states, keyboard
navigation, reachable Save/Close controls, and resize while an overlay is open.
+131
View File
@@ -0,0 +1,131 @@
# Using and administering Furumusic
[Project overview](../README.md) · [Installation](setup.md) · [Development and tests](development.md)
## Access and public sharing
OIDC identifies accounts by issuer and subject. Matching admin groups take
precedence over matching user groups, and either SSO grant takes precedence over
a local role. Without matching groups (including an empty group configuration),
a new account waits for approval in **Admin → Users**. Any instance administrator
can approve it as a user or administrator. The waiting page updates automatically.
On subsequent SSO logins the group grant is refreshed: if it disappears, only an
independently assigned local role preserves access. Existing password accounts
keep their local roles; existing OIDC-only accounts retain their last SSO grant
until the next login, without receiving an implicit local approval.
Sharing creates an unguessable `/share/{token}` link to a snapshot of track IDs,
including their order and repetitions. Guests and accounts awaiting approval can
play and download only the tracks in that snapshot, using the regular player.
They cannot browse the library, search, use recommendations, or write personal
history. Signing in from a share returns to that share; signing in from the root
shows only the approval page until access is granted. Track info offers a browser
download of the original audio file. The old radio implementation is removed.
Migration `m_0053_local_approval_and_public_shares` deletes the old share records.
Old track/release/playlist URL routes are removed, with no compatibility layer.
Link expiry, cleanup, and revocation are not part of this implementation.
## Importing music
Users can add audio files from the web interface or ask the server to download
selected files from a torrent. Both routes feed the same import pipeline, so a
library remains consistent regardless of where its files came from.
The importer combines embedded tags, filenames, folder structure, and existing
catalog context. With an OpenAI-compatible language model configured, it can
normalize artist and release names, separate featured artists, recover track
numbers and release types, and flag ambiguous results for a user to approve.
Cover art is taken from nearby image files or embedded artwork when available.
The inbox and permanent library are separate directories. New files are first
processed in the inbox and are moved into the organized library only after
their metadata has been accepted.
## Importing into playlists
The player's download manager offers **Add downloads to a playlist** for file
and folder uploads and torrents, as well as YouTube. Choose an existing owned
playlist or create one before starting; leaving the choice empty imports only
into the library. Selected audio tracks are appended after processing or manual
approval, including files resolved to tracks already in the library.
Migration `m_0052_add_import_playlist_destinations` persists the destination and
completion receipts. Retries and restarts retain the choice, avoid duplicates,
and do not re-add tracks subsequently removed by the user. A started batch keeps
its destination for its remaining files.
## Federation
Federation is optional. Independent Furumusic and Furumi players that use the
same Network ID discover one another as a logical network. Each peer keeps its
own library and can continue working alone.
When federation is enabled, local and remote artists, releases, and tracks can
appear in the same search and library views. Missing audio is streamed from an
available peer and can optionally be retained locally. Similarity search also
stays decentralized: embeddings and exact ranking remain on the instance that
owns the music.
Trusted-device pairing is separate from public catalog discovery. It connects
a user's own Furumi players so likes, playlists, playback state, and control can
move between approved devices.
## Admin statistics
The only admin interface is `/admin/v2`, also reachable from `/admin/`.
**Statistics** shows listening totals, a timeline, artist/track/release rankings,
and paginated history. Select an artist or track to see its listeners, then a
listener to see their history within the same filters. The **Users** list links
to each user's full statistics.
Periods use UTC. Counts come from the synchronized `listen_event` history: a
natural finish, half of a track, or four minutes qualifies as a play. Interrupted
sessions under five seconds are not retained. Short retained sessions contribute
to listened time but not play counts. The source filter separates this instance
from synchronized devices. Artist rankings use recorded artist names, including
featured credits; the same artist is counted once per event. Existing history
remains available when its local audio file is deleted. Library and service
cards show current instance totals, independently of the listening filters.
Migration `m_0051_add_listen_statistics_indexes` adds time and content indexes.
The old admin pages and `/admin/debug` are removed; first-run setup remains at
`/admin/setup`.
## Metadata Repair
Admin → Library Tools provides a chat for editing the selected library resources.
Use **Show related**, then **Deselect all** to choose only the resources needed
for the task. Selecting a release includes its tracks; individual tracks can
then be unchecked to exclude them. Unselected artists remain read-only context
and their IDs can still be used in credits. Releases show their years; tracks
show their source release.
The assistant sees the complete selected scope and replaces the proposed plan
after every clarification. Expand **Proposed changes** in the chat to review or
edit it before applying. Plans support moving tracks, creating releases, merging
releases, and deleting artists, releases, or tracks. Release deletion requires
explicit moves or deletion of all its tracks. Artist deletion detaches credits
and requires all credited releases and tracks to be included.
Applied plans are transactional and can be undone from History. Metadata Repair
retains audio and artwork files for Undo. Undo refuses to overwrite subsequent
metadata, playback, or federation changes.
## Last.fm popularity updates
The `lastfm_popularity` job defaults to **light** mode: it requests popularity
only for tracks without a completed lookup or with a changed title or primary
artist. Both matches (including zero counts) and explicit Last.fm “Track not
found” results are skipped on subsequent light runs. HTTP errors, timeouts,
invalid responses, and other API errors remain eligible for retry. A failed
full refresh also makes that track eligible for the next light run.
Choose **Full: refresh all visible tracks** in the task's admin parameters to
refresh existing statistics and retry previous misses. The options endpoint
`POST /admin/v2/api/jobs/lastfm_popularity/run-options` accepts
`{"refresh_existing": true}`; an empty object, scheduled runs, and the ordinary
run endpoint use light mode. Neither mode limits the number of tracks processed.
An authoritative miss clears current statistics while preserving their history.
The migration preserves existing popularity; legacy misses need one more lookup
because older versions did not persist them.
+122
View File
@@ -0,0 +1,122 @@
# Development
[Project overview](../README.md) · [Installation](setup.md) · [Admin UI conventions](admin-ui.md)
## Architecture
Furumusic is written in Rust on the
[Cot](https://cot.rs) web framework. PostgreSQL stores the catalog, accounts,
playlists, configuration, and background-job state. Audio inspection uses
Symphonia, torrent downloads use librqbit, and the shared `music-dht`/Frid
protocol stack provides decentralized catalog search, media transfer, and
connected-device synchronization.
The browser interface and JSON API are served by the same application. Import,
artwork, metadata enrichment, similarity indexing, and maintenance run as
durable background jobs rather than blocking playback requests.
## Build profiles
Development and test builds use basic optimization (`opt-level = 1`) for
dependencies to keep macOS unwind tables below the compact-unwind size limit.
Application code stays unoptimized; debug symbols, assertions and panic
unwinding remain enabled. The first build compiles dependencies with these
settings, then reuses them from Cargo's cache. Dependency stepping in a debugger
can be less exact because of optimization. Release settings are independent.
See the [Cargo profile override documentation](https://doc.rust-lang.org/cargo/reference/profiles.html#overrides) for dependency-specific settings.
## Container builds and CI
CI uses Rust 1.97.0 and cargo-chef 0.1.74 to cache compiled dependencies separately
from application sources. Buildx imports and exports intermediate layers through
`ultradesu/furumusic:buildcache` (`mode=max`). After the first build, changes to
source code, templates or prompts reuse the dependency layer when its recipe and
toolchain are unchanged. Both dependency and application builds use `--locked`.
Update the pinned build tools in `Dockerfile`; changing them rebuilds the cache.
## Contributing
Bug reports, design discussions, and patches are welcome. Before submitting a
change, run:
```bash
cargo fmt --all -- --check
cargo clippy --all-targets -- -D warnings
cargo test --all-targets
```
Last.fm database tests use temporary tables on a disposable PostgreSQL database:
```bash
FURUMUSIC_LASTFM_TEST_DATABASE_URL=postgres://user:pass@localhost/test_db \
cargo test lastfm_popularity -- --include-ignored
```
## Access and sharing tests
The access regression suite uses a disposable migrated database and a local OIDC
provider with signed tokens and PKCE:
```bash
node --test tests/*.test.cjs
FURU_ACCESS_TEST_DATABASE_URL=postgresql://... cargo test postgres_approval_survives_sso_changes_without_implicit_grants -- --ignored
# Fresh disposable instance on :18048, media root /tmp/furumi-access-media,
# PostgreSQL container furumi-access-test-pg, database furumi_access_test:
node tests/browser-access-sharing.cjs
```
The browser test requires Playwright (`PLAYWRIGHT_MODULE`) and Chrome
(`CHROME_PATH`), and uses local port 18049 for its OIDC provider. It checks
approval, SSO precedence and group removal, guest playback and downloads,
unauthorized track substitution, and desktop/mobile player behavior.
## Statistics tests
```bash
node --test tests/*.test.cjs
cargo test admin:: -- --skip postgres_statistics_drilldown_and_pagination
# Use a disposable PostgreSQL; this test creates connection-local temporary tables.
FURU_STATISTICS_TEST_DATABASE_URL=postgresql://... cargo test postgres_statistics_drilldown_and_pagination -- --ignored
```
`tests/browser-statistics.cjs` additionally exercises a fresh disposable instance
at `FURU_TEST_URL` (default `http://127.0.0.1:3018`) and seeds the disposable Docker
container `furumi-statistics-test-pg`. It requires Playwright (or
`PLAYWRIGHT_MODULE`) and Chrome (or `CHROME_PATH`). Never point this test at a
live service.
## Metadata Repair tests
```bash
node --test tests/admin_metadata_repair.test.cjs
cargo test admin::metadata_fix::tests
```
`tests/browser-metadata-repair.cjs` checks the chat and plan updates, a four-release
merge, deletion and restoration of tracks and artist credits, playlists, playback
queues, and undo conflicts. Run it only against a disposable instance and a
PostgreSQL container named `furumi-repair-test-pg`, with database
`furumi_repair_test`. Set `FURU_TEST_URL`, `FURU_REPAIR_TEST_PG`, `CHROME_PATH`, and
`PLAYWRIGHT_MODULE` as needed. It seeds `tests/metadata_repair_fixture.sql` after
creating the test administrator. Set `FURU_REPAIR_SKIP_SEED=1` for a seeded database.
With `FURU_REPAIR_TEST_MODEL=1`, it additionally checks the reported release-only
selection and full ordered tracklist against the configured model, applies and
undoes that plan, and verifies individual track exclusions.
## Import destination tests
```bash
node --test tests/import_playlists.test.cjs
# Disposable PostgreSQL; both tests use temporary tables.
FURU_IMPORT_TEST_DATABASE_URL=postgresql://... cargo test import_destinations -- --ignored
FURU_IMPORT_TEST_DATABASE_URL=postgresql://... cargo test torrent_playlist -- --ignored
```
`tests/browser-import-playlists.cjs` checks the file upload flow, database
reconciliation and the torrent picker on desktop and mobile. It requires a fresh
migrated instance with the import agent disabled at `FURU_TEST_URL` (default
`http://127.0.0.1:3019`), the disposable PostgreSQL container
`furumi-import-playlist-test-pg` with database `furumi_import_test`, and Playwright
and Chrome configured as above. It uses a local torrent preview fixture and
simulated imported tracks, without downloading external torrents.
+57
View File
@@ -0,0 +1,57 @@
# Installation and configuration
[Project overview](../README.md) · [Administration guide](administration.md)
## Build and run
Furumusic requires PostgreSQL and a Rust toolchain with Rust 2024 edition
support. Create an empty database, provide its connection URL, and start the
server:
```bash
export FURU_DATABASE_URL='postgresql://furumusic:password@127.0.0.1/furumusic'
cargo run --release --locked
```
Open <http://127.0.0.1:8000/admin/setup> to create the first administrator.
After setup, configure the inbox and library directories under **Admin →
Settings** before importing music.
To listen on another address or port:
```bash
cargo run --release --locked -- -l 0.0.0.0:8000
```
A Nix development shell is included for Linux and macOS:
```bash
nix develop
cargo run --locked
```
The repository also contains a multi-stage `Dockerfile` for building a small
runtime image. A deployment must provide PostgreSQL plus persistent, writable
volumes for the inbox and music library.
## Configuration
Most settings can be changed from the administration interface. Every setting
also has a `FURU_`-prefixed environment variable; environment values take
priority over values stored in PostgreSQL.
The settings needed for a useful first installation are:
| Setting | Purpose |
| --- | --- |
| `FURU_DATABASE_URL` | PostgreSQL connection URL; required to run the service |
| `FURU_AGENT_INBOX_DIR` | Temporary inbox for uploads and downloaded files |
| `FURU_AGENT_STORAGE_DIR` | Permanent, organized music library |
| `FURU_AGENT_ENABLED` | Enables the background metadata import pipeline |
| `FURU_AGENT_LLM_URL` | Base URL of an OpenAI-compatible model server |
| `FURU_AGENT_LLM_MODEL` | Model used to recognize and normalize metadata |
| `FURU_FEDERATION_ENABLED` | Publishes the library and enables peer discovery |
| `FURU_FEDERATION_NETWORK_ID` | Joins peers with the same value into one logical network |
AI recognition, federation, similarity search, Last.fm, and OIDC are optional.
A local password-authenticated server can be used without any of them.
+25
View File
@@ -0,0 +1,25 @@
<aside class="sidebar" id="admin-navigation" :class="{'is-open': menuOpen}" :data-compact="isCompact" :inert="isCompact && !menuOpen" :role="isCompact ? 'dialog' : null" :aria-modal="isCompact && menuOpen ? 'true' : null" aria-label="Admin navigation" tabindex="-1" x-effect="adminOverlay.sync($el, isCompact && menuOpen)" @keydown="adminOverlay.keydown($event, $el)">
<div class="brand">
<div><div class="brand-title">FuruMusic <span class="version">v{{ version }}</span></div><div class="admin-user">{{ user_name }} · {{ user_role }}</div></div>
<button class="icon-btn nav-close" data-dialog-close aria-label="Close navigation" @click="closeMenu()"><i data-lucide="x"></i></button>
</div>
<nav aria-label="Administration" class="nav-sections" @click="if ($event.target.closest('.nav-btn')) closeMenu()">
<div class="nav-group">
<div class="nav-label">Operations</div>
<button class="nav-btn" :class="{active: activeView === 'reviews'}" :aria-current="activeView === 'reviews' ? 'page' : null" @click="openReviews()"><i data-lucide="inbox"></i><span>Review Queue</span><span class="nav-count" x-text="reviewTotalAll()"></span></button>
<button class="nav-btn" :class="{active: activeView === 'jobs'}" :aria-current="activeView === 'jobs' ? 'page' : null" @click="openJobs()"><i data-lucide="calendar-clock"></i><span>Tasks</span><span class="nav-count" x-text="jobs.length || 0"></span></button>
</div>
<div class="nav-group">
<div class="nav-label">Music</div>
<button class="nav-btn" :class="{active: activeView === 'library'}" :aria-current="activeView === 'library' ? 'page' : null" @click="openLibrary(libraryKind)"><i data-lucide="library"></i><span>Library Workbench</span><span class="nav-count" x-text="fmt(stats.tracks || 0)"></span></button>
<button class="nav-btn" :class="{active: activeView === 'tools'}" :aria-current="activeView === 'tools' ? 'page' : null" @click="openTools()"><i data-lucide="wrench"></i><span>Library Tools</span></button>
<button class="nav-btn" :class="{active: activeView === 'statistics'}" :aria-current="activeView === 'statistics' ? 'page' : null" @click="openStatistics()"><i data-lucide="chart-no-axes-combined"></i><span>Statistics</span></button>
</div>
<div class="nav-group">
<div class="nav-label">Instance</div>
<button class="nav-btn" :class="{active: activeView === 'users'}" :aria-current="activeView === 'users' ? 'page' : null" @click="openUsers()"><i data-lucide="users"></i><span>Users</span><span class="nav-count" x-text="users.online_count ? users.online_count + ' online' : ''"></span></button>
<button class="nav-btn" :class="{active: activeView === 'settings'}" :aria-current="activeView === 'settings' ? 'page' : null" @click="openSettings()"><i data-lucide="settings"></i><span>Settings</span></button>
</div>
</nav>
<a class="nav-player btn" href="/"><i data-lucide="music-2"></i>Back to player</a>
</aside>
+193
View File
@@ -0,0 +1,193 @@
<style>
/* Shared admin UI contract. Keep breakpoints in sync with admin/ui.html. */
:root { --admin-gap:16px; --admin-touch:44px; --admin-header:64px; --admin-radius:10px; }
html { overscroll-behavior:none; }
:focus-visible { outline:2px solid var(--accent); outline-offset:3px; }
.admin-shell { min-width:0; }
.sidebar { overflow:auto; overscroll-behavior:contain; padding-bottom:env(safe-area-inset-bottom); }
.brand { display:flex; align-items:center; justify-content:space-between; gap:12px; }
.nav-player { margin:12px; margin-top:auto; min-height:44px; flex:none; }
.nav-btn { min-height:44px; height:auto; padding-block:10px; }
.nav-group { padding-block:8px; }
.nav-label { letter-spacing:.08em; }
.nav-btn.active { background:rgba(29,185,84,.12); box-shadow:inset 3px 0 var(--accent); }
.menu-toggle, .nav-close, .nav-backdrop, .workspace-tabs, .section-jump { display:none; }
.main { overscroll-behavior:contain; scrollbar-gutter:stable; }
.main.is-locked { overflow:hidden; }
.topbar { min-height:var(--admin-header); height:auto; }
.top-actions { flex:none; }
.content { min-width:0; padding:var(--admin-gap); }
.content > *, .panel-head > *, .toolbar > *, .modal-body > *, .settings-section > *, .image-editor > * { min-width:0; }
.panel-head, .toolbar, .action-strip { flex-wrap:wrap; }
.panel-head > .toolbar { margin-left:auto; }
.toolbar { max-width:100%; }
.search { max-width:100%; min-width:0; }
.btn { text-decoration:none; white-space:normal; line-height:1.3; }
.icon-btn { flex:none; }
.segmented { max-width:100%; min-width:0; overflow:auto; flex-wrap:nowrap; }
.seg-btn { flex:none; }
.panel-title strong, .panel-title span, .setting-help, .selection-summary, .repair-context { overflow-wrap:anywhere; }
.table-wrap { max-width:100%; overscroll-behavior:contain; }
.table-wrap:focus-visible { outline-offset:-3px; }
.jobs-page { grid-template-columns:minmax(0,1fr) minmax(280px,340px); height:calc(100dvh - 100px); }
.run-row { width:100%; color:inherit; text-align:left; background:transparent; font:inherit; }
.row-link { display:block; max-width:100%; padding:0; background:transparent; color:inherit; text-align:left; cursor:pointer; }
.row-link:hover { text-decoration:underline; }
.job-fact > .btn { grid-column:2; justify-self:start; }
.job-fact > form { grid-column:1 / -1; }
.task-form { position:static; max-height:100%; }
.settings-section { scroll-margin-top:calc(var(--admin-header) + 70px); }
.settings-federation-body { grid-template-columns:minmax(0,4fr) minmax(0,8fr); }
.download-method-controls { grid-template-columns:minmax(0,.75fr) minmax(0,1.25fr); }
.proxy-row { grid-template-columns:minmax(0,1.4fr) minmax(0,.8fr) minmax(0,.8fr) auto; }
.field { display:block; min-width:0; }
.modal-backdrop { padding:24px; overscroll-behavior:contain; }
.modal { display:flex; flex-direction:column; width:min(760px,100%); max-width:100%; max-height:calc(100dvh - 48px); }
.modal.user-modal { width:min(860px,100%); }
.modal.merge-modal { width:min(1180px,100%); }
.modal-head { flex:none; min-width:0; padding:12px 16px; }
.modal-head [data-dialog-close] { flex:none; min-width:44px; min-height:44px; }
.modal-body { min-height:0; max-height:none; overflow:auto; overscroll-behavior:contain; padding:16px; }
.dialog-actions { position:sticky; bottom:-16px; z-index:4; display:flex; align-items:center; justify-content:flex-end; flex-wrap:wrap; gap:8px; margin:16px -16px -16px; padding:12px 16px; border-top:1px solid var(--border-color); background:var(--bg-secondary); }
.merge-footer.dialog-actions { justify-content:space-between; }
.track-field { min-width:0; margin:0; }
.track-field > span { display:none; }
.toast { z-index:50; max-width:min(420px,calc(100vw - 24px)); bottom:max(18px,env(safe-area-inset-bottom)); overflow-wrap:anywhere; }
.repair-plan-body { max-width:100%; }
.repair-work, .repair-side { min-width:0; }
.repair-manual { max-width:100%; overflow:auto; }
.repair-diff { table-layout:auto; }
.settings-actions { padding-bottom:max(12px,env(safe-area-inset-bottom)); }
@media (max-width:1279px) {
.workspace-tabs { display:flex; gap:4px; padding:4px; margin-bottom:12px; border:1px solid var(--border-color); border-radius:8px; background:var(--bg-secondary); }
.workspace-tabs button { flex:1; min-width:0; min-height:44px; padding:8px; border-radius:5px; background:transparent; color:var(--text-secondary); cursor:pointer; }
.workspace-tabs [aria-selected="true"] { background:var(--bg-active); color:var(--text-primary); }
.jobs-page { display:block; height:auto; }
.jobs-page .jobs-list-panel, .jobs-page .task-form, .jobs-page .run-log-panel { display:none; max-height:none; }
.jobs-page[data-task-pane="list"] .jobs-list-panel,
.jobs-page[data-task-pane="details"] .task-form,
.jobs-page[data-task-pane="logs"] .run-log-panel { display:flex; }
.task-form-body { overflow:visible; }
.run-log-body { min-height:300px; overflow:visible; }
.run-log-output { min-height:50dvh; max-height:70dvh; }
.settings-layout { grid-template-columns:minmax(0,1fr); grid-template-areas:"access" "oidc" "agent" "agentstatus" "similarity" "similaritystatus" "downloads" "federation" "lastfm" "developer" "actions"; }
.settings-federation-body { grid-template-columns:minmax(0,1fr); }
.repair-shell { grid-template-columns:250px minmax(0,1fr); }
}
@media (max-width:1023px) {
:root { --admin-gap:16px; }
.admin-shell { grid-template-columns:minmax(0,1fr); }
.sidebar { position:fixed; inset:0 auto 0 0; z-index:25; width:min(320px,calc(100vw - 48px)); height:100dvh; transform:translateX(-100%); visibility:hidden; transition:transform .18s ease, visibility .18s; padding-top:env(safe-area-inset-top); box-shadow:16px 0 48px #0006; }
.sidebar.is-open { transform:translateX(0); visibility:visible; }
.nav-backdrop { display:block; position:fixed; inset:0; z-index:24; background:#0009; }
.menu-toggle, .nav-close { display:inline-flex; align-items:center; justify-content:center; min-width:44px; min-height:44px; }
.topbar { display:grid; grid-template-columns:44px minmax(0,1fr) auto; gap:10px; padding:10px 16px; padding-top:max(10px,env(safe-area-inset-top)); }
.page-title h1 { font-size:18px; }
.page-title p { line-height:1.4; }
.panel-head { gap:12px; }
.panel-head > .toolbar { margin-left:0; }
.library-row { grid-template-columns:32px minmax(0,1fr) 110px; }
.library-row .tags { grid-column:2 / -1; grid-row:2; }
.library-row > .badge { grid-column:3; grid-row:1; justify-self:end; }
.section-jump { display:flex; align-items:center; gap:12px; margin-bottom:16px; font-size:13px; color:var(--text-secondary); }
.section-jump select { flex:1; width:auto; }
.primary-line, .secondary-line { white-space:normal; overflow-wrap:anywhere; }
.users-table, .statistics-table { min-width:700px; }
}
@media (max-width:767px) {
:root { --admin-gap:12px; }
.topbar { gap:8px; padding-inline:12px; }
.top-actions { gap:6px; }
.top-actions .btn { width:44px; height:44px; padding:0; justify-content:center; }
.top-action-label, .page-title p { display:none; }
.page-title h1 { font-size:17px; overflow-wrap:anywhere; }
.btn, .icon-btn, .seg-btn { min-height:44px; height:auto; }
.icon-btn { width:44px; }
.btn { padding:10px 12px; }
.search, .setting-field input, .setting-field select, .field input, .field select, .field textarea, .setting-field textarea, .proxy-row input, .download-method-controls select, .youtube-cookie-picker select, .repair-composer textarea { font-size:16px; min-height:44px; }
.search { width:100%; }
.toolbar { gap:8px; }
.panel-head { padding:12px; align-items:stretch; }
.panel-head > .toolbar { width:100%; }
.toolbar > input.search { flex:1 1 180px; }
.segmented { width:100%; }
.seg-btn { min-width:max-content; }
.action-strip { padding:12px; gap:12px; align-items:stretch; }
.action-strip > .toolbar { width:100%; }
.action-strip > .selection-summary { flex-basis:100%; }
.stats-strip, .statistics-summary, .user-summary-grid, .user-profile-facts, .user-stats-grid { grid-template-columns:repeat(2,minmax(0,1fr)); }
.stat-cell { padding:12px; }
.stat-value { font-size:24px; }
.stats-strip { gap:8px; }
.table-wrap, .review-table-wrap, .users-table-wrap, .job-table-wrap { max-height:none; overflow:visible; }
.responsive-table { display:block; table-layout:auto; min-width:0; width:100%; }
.responsive-table thead { position:absolute; width:1px; height:1px; overflow:hidden; clip-path:inset(50%); }
.responsive-table tbody { display:block; }
.responsive-table tr { display:grid; grid-template-columns:repeat(2,minmax(0,1fr)); gap:12px; margin:0 12px 12px; padding:14px; border:1px solid var(--border-color); border-radius:8px; background:var(--bg-primary); }
.responsive-table tr.active { border-color:var(--accent); }
.responsive-table td { display:flex; flex-direction:column; align-items:flex-start; gap:5px; width:auto; height:auto; min-width:0; padding:0; border:0; overflow-wrap:anywhere; white-space:normal; }
.responsive-table td::before { content:attr(data-label); color:var(--text-subdued); font-size:10px; font-weight:750; text-transform:uppercase; letter-spacing:.04em; }
.responsive-table td[data-primary], .responsive-table td[data-label="Actions"], .responsive-table td[data-label="Account"], .responsive-table td[data-label="Tags"] { grid-column:1 / -1; }
.responsive-table td[data-primary] { font-size:15px; }
.responsive-table .primary-line { font-size:14px; }
.responsive-table .secondary-line { line-height:1.5; }
.responsive-table .tags { max-height:none; }
.responsive-table .inline-runs { flex-wrap:wrap; }
.responsive-table .run-chip { min-height:36px; max-width:none; }
.responsive-table .toolbar { justify-content:flex-start; flex-wrap:wrap; }
.row-link { min-height:44px; display:flex; align-items:center; }
.check { width:22px; height:22px; }
.library-row { grid-template-columns:26px minmax(0,1fr) auto; padding:12px; gap:10px; }
.library-row > .tags { max-height:none; }
.editor-grid, .settings-grid, .federation-status-grid, .download-method-controls, .proxy-row, .metadata-backfill-options .option-grid { grid-template-columns:minmax(0,1fr); }
.setting-field, .settings-wide, .setting-field.settings-short { max-width:none; }
.settings-grid, .settings-federation-body, .probe-body { padding:12px; }
.settings-federation-body .settings-grid, .settings-federation-body .probe-body { padding:0; }
.youtube-cookie-picker, .youtube-cookie-upload, .transport-log-head { align-items:stretch; flex-direction:column; }
.settings-actions { position:static; }
.settings-actions .toolbar { justify-content:flex-end; }
.modal-backdrop { padding:0; }
.modal, .modal.user-modal, .modal.merge-modal { width:100%; height:100dvh; max-height:100dvh; border:0; border-radius:0; }
.modal-head { padding-top:max(12px,env(safe-area-inset-top)); }
.modal-body { flex:1; padding-bottom:max(16px,env(safe-area-inset-bottom)); }
.dialog-actions { padding-bottom:max(12px,env(safe-area-inset-bottom)); }
.modal-body .toolbar { flex-wrap:wrap; }
.image-editor { grid-template-columns:96px minmax(0,1fr); }
.image-preview { width:96px; }
.image-actions { flex-wrap:wrap; }
.image-actions input[type="file"] { max-width:100%; }
.user-activity-row { grid-template-columns:44px minmax(0,1fr); }
.user-activity-cover { width:44px; height:44px; }
.user-activity-time { grid-column:2; min-width:0; text-align:left; }
.user-activity-title, .user-activity-meta, .user-activity-sub, .user-profile-facts strong { white-space:normal; overflow-wrap:anywhere; }
.release-track-head, .merge-track-head { display:none; }
.merge-track-list { min-width:0; }
.release-track-row, .merge-track-row { grid-template-columns:repeat(2,minmax(0,1fr)); padding:12px; gap:10px; }
.release-track-row > div, .merge-track-row > div { grid-column:1 / -1; }
.release-track-row .icon-btn { justify-self:end; grid-column:2; }
.track-field > span { display:block; color:var(--text-subdued); font-size:11px; margin-bottom:6px; }
.release-track-title, .release-track-meta { white-space:normal; overflow-wrap:anywhere; }
.merge-track-row > span { grid-column:1 / -1; }
.merge-order-actions { justify-content:flex-end; gap:8px; }
.merge-release-grid { grid-template-columns:minmax(0,1fr); }
.repair-shell { grid-template-columns:minmax(0,1fr); height:auto; min-height:0; }
.repair-side .panel:first-child .repair-scroll { max-height:260px; }
.repair-work .repair-chat { min-height:420px; height:65dvh; max-height:720px; }
.repair-plan-actions { align-items:stretch; flex-direction:column; }
.repair-message { max-width:100%; }
.repair-composer { flex-wrap:wrap; }
.repair-composer textarea { flex-basis:100%; }
.repair-composer .btn { margin-left:auto; }
.repair-diff { min-width:760px; }
.repair-manual { overscroll-behavior:contain; }
.statistics-ranking-head { align-items:stretch; flex-direction:column; }
.statistics-filters { padding:12px; }
.statistics-toolbar label { flex:1 1 140px; min-width:0; }
.statistics-toolbar .search { width:100%; }
.statistics-chart { padding:16px; }
.statistics-service-grid { grid-template-columns:minmax(0,1fr); padding:12px; }
.job-fact { grid-template-columns:70px minmax(0,1fr); }
.job-fact span:last-child { white-space:normal; overflow-wrap:anywhere; }
}
@media (prefers-reduced-motion:reduce) { .sidebar { transition:none; } }
</style>
+7 -7
View File
@@ -5,13 +5,13 @@
{% block head_extra %}
<style>
* { margin: 0; padding: 0; box-sizing: border-box; }
body { font-family: system-ui, -apple-system, sans-serif; background: #f5f5f5; color: #333; display: flex; justify-content: center; align-items: center; min-height: 100vh; }
.setup-card { background: #fff; border-radius: 8px; box-shadow: 0 2px 8px rgba(0,0,0,.12); padding: 2rem 2.5rem; width: 100%; max-width: 400px; }
body { font-family: system-ui, -apple-system, sans-serif; background: #f5f5f5; color: #333; display: flex; justify-content: center; align-items: center; min-height: 100dvh; padding: max(16px, env(safe-area-inset-top)) 16px max(16px, env(safe-area-inset-bottom)); }
.setup-card { background: #fff; border-radius: 8px; box-shadow: 0 2px 8px rgba(0,0,0,.12); padding: clamp(20px, 5vw, 40px); width: 100%; max-width: 400px; }
.setup-card h1 { margin-bottom: 1.5rem; font-size: 1.5rem; text-align: center; }
.setup-card label { display: block; margin-bottom: .25rem; font-weight: 600; font-size: .9rem; }
.setup-card input[type="text"],
.setup-card input[type="password"] { width: 100%; padding: .5rem .7rem; margin-bottom: 1rem; border: 1px solid #ccc; border-radius: 4px; font-size: .95rem; }
.setup-card button { display: block; width: 100%; padding: .6rem; border: none; border-radius: 4px; font-size: 1rem; cursor: pointer; background: #1a1a2e; color: #fff; }
.setup-card input[type="password"] { width: 100%; padding: .5rem .7rem; margin-bottom: 1rem; border: 1px solid #ccc; border-radius: 4px; font-size: 16px; min-height: 44px; }
.setup-card button { display: block; width: 100%; padding: .6rem; min-height: 44px; border: none; border-radius: 4px; font-size: 1rem; cursor: pointer; background: #1a1a2e; color: #fff; }
.setup-card button:hover { background: #16213e; }
.setup-card .flash { color: #856404; background: #fff3cd; padding: .5rem .75rem; border-radius: 4px; margin-bottom: 1rem; text-align: center; font-size: .9rem; }
</style>
@@ -27,11 +27,11 @@
<form method="post" action="/admin/setup">
<label for="username">{{ t.setup_username }}</label>
<input type="text" name="username" id="username" required>
<input type="text" name="username" id="username" autocomplete="username" required>
<label for="password">{{ t.setup_password }}</label>
<input type="password" name="password" id="password" required>
<input type="password" name="password" id="password" autocomplete="new-password" required>
<label for="confirm_password">{{ t.setup_confirm }}</label>
<input type="password" name="confirm_password" id="confirm_password" required>
<input type="password" name="confirm_password" id="confirm_password" autocomplete="new-password" required>
<button type="submit">{{ t.setup_submit }}</button>
</form>
</div>
File diff suppressed because it is too large. Load diff
+120
View File
@@ -0,0 +1,120 @@
<script>
// Shared responsive shell state. Business data stays in adminV2().
function adminUI() {
return {
menuOpen: false,
isCompact: false,
isTaskStacked: false,
taskPane: 'list',
initUI() {
const compact = window.matchMedia('(max-width: 1023px)');
const stacked = window.matchMedia('(max-width: 1279px)');
const update = () => {
this.isCompact = compact.matches;
this.isTaskStacked = stacked.matches;
if (!this.isCompact) this.menuOpen = false;
};
update();
compact.addEventListener('change', update);
stacked.addEventListener('change', update);
this._uiCleanup = () => {
compact.removeEventListener('change', update);
stacked.removeEventListener('change', update);
};
this.$watch('activeView', () => {
this.closeMenu();
if (this.$refs?.main) this.$refs.main.scrollTop = 0;
});
},
destroy() {
this._uiCleanup?.();
if (this.poller) clearInterval(this.poller);
},
openMenu() { this.menuOpen = true; },
closeMenu() { this.menuOpen = false; },
showTaskPane(pane) {
this.taskPane = pane;
if (this.isTaskStacked) this.$nextTick(() => document.getElementById('task-tab-' + pane)?.focus());
},
taskTabKeydown(event) {
const panes = ['list', 'details', 'logs'];
const index = panes.indexOf(this.taskPane);
const keys = {ArrowRight:(index + 1) % 3, ArrowLeft:(index + 2) % 3, Home:0, End:2};
if (!(event.key in keys)) return;
event.preventDefault();
this.showTaskPane(panes[keys[event.key]]);
},
jumpToSettings(section) {
const target = document.getElementById('settings-' + section);
if (!target) return;
target.scrollIntoView({behavior:window.matchMedia('(prefers-reduced-motion: reduce)').matches ? 'instant' : 'smooth', block:'start'});
target.setAttribute('tabindex', '-1');
target.focus({preventScroll:true});
},
};
}
// All modal dialogs and the mobile navigation share one focus/scroll lifecycle.
// State is outside Alpine reactivity so opening a dialog does not retrigger x-effect.
const adminOverlay = (() => {
const states = new WeakMap();
const stack = [];
const frame = callback => window.requestAnimationFrame(callback);
const focusables = element => [...element.querySelectorAll('button:not(:disabled), a[href], input:not(:disabled), select:not(:disabled), textarea:not(:disabled), [tabindex="0"]')]
.filter(node => node.getClientRects().length && !node.closest('[inert]'));
function updateBackground() {
const top = stack.at(-1);
const main = document.getElementById('admin-main');
const nav = document.getElementById('admin-navigation');
if (main) { main.inert = !!top; main.classList.toggle('is-locked', !!top); }
if (nav) nav.inert = (top && top !== nav) || (nav.dataset.compact === 'true' && !nav.classList.contains('is-open'));
for (const entry of stack) entry.inert = entry !== top;
}
function sync(element, open) {
const previous = states.get(element);
if (previous?.open === open) return;
states.set(element, {open, returnFocus:open ? document.activeElement : previous?.returnFocus});
if (open) {
stack.push(element);
frame(() => {
if (stack.at(-1) !== element) return;
updateBackground();
const dialog = element.querySelector('[role="dialog"]') || element;
dialog.focus({preventScroll:true});
});
} else {
const index = stack.indexOf(element);
if (index !== -1) stack.splice(index, 1);
element.inert = element.id !== 'admin-navigation';
frame(() => {
updateBackground();
const top = stack.at(-1);
if (top) {
if (!top.contains(document.activeElement)) (top.querySelector('[role="dialog"]') || top).focus({preventScroll:true});
} else if (previous?.open) {
const target = previous.returnFocus;
if (target?.isConnected && target.getClientRects().length && !target.closest('[inert]')) target.focus({preventScroll:true});
else document.querySelector('.menu-toggle')?.focus({preventScroll:true});
}
});
}
}
function keydown(event, element) {
if (stack.at(-1) !== element) return;
if (event.key === 'Escape' && !event.defaultPrevented) {
const close = element.querySelector('[data-dialog-close]');
if (close && !close.disabled) { event.preventDefault(); event.stopPropagation(); close.click(); }
} else if (event.key === 'Tab') {
const nodes = focusables(element);
const first = nodes[0], last = nodes.at(-1);
if (!first) { event.preventDefault(); return; }
if (event.shiftKey && (document.activeElement === first || !nodes.includes(document.activeElement))) {
event.preventDefault(); last.focus();
} else if (!event.shiftKey && (document.activeElement === last || !nodes.includes(document.activeElement))) {
event.preventDefault(); first.focus();
}
}
}
return {sync, keydown};
})();
</script>
+104 -2230
View File
File diff suppressed because it is too large. Load diff
+2 -1
View File
@@ -3,7 +3,8 @@ const { readFileSync } = require('node:fs');
const { test } = require('node:test');
const vm = require('node:vm');
const template = readFileSync(`${__dirname}/../templates/admin/v2.html`, 'utf8');
const script = template.match(/<script>\s*(function adminV2\(\)[\s\S]*?)<\/script>/)[1];
const ui = readFileSync(`${__dirname}/../templates/admin/ui.html`, 'utf8').match(/<script>([\s\S]*?)<\/script>/)[1];
const script = ui + '\n' + template.match(/<script>\s*(function adminV2\(\)[\s\S]*?)<\/script>/)[1];
function createApp() {
const context = vm.createContext({URLSearchParams});
vm.runInContext(script, context);
+2 -1
View File
@@ -3,7 +3,8 @@ const {readFileSync} = require('node:fs');
const {test} = require('node:test');
const vm = require('node:vm');
const template = readFileSync(`${__dirname}/../templates/admin/v2.html`, 'utf8');
const script = template.match(/<script>\s*(function adminV2\(\)[\s\S]*?)<\/script>/)[1];
const ui = readFileSync(`${__dirname}/../templates/admin/ui.html`, 'utf8').match(/<script>([\s\S]*?)<\/script>/)[1];
const script = ui + '\n' + template.match(/<script>\s*(function adminV2\(\)[\s\S]*?)<\/script>/)[1];
function app() {
const context = vm.createContext({URLSearchParams, Date}); vm.runInContext(script, context);
const a = context.adminV2(); a.icons = () => {}; a.setRoute = () => {}; return a;
+2 -1
View File
@@ -4,7 +4,8 @@ const { test } = require('node:test');
const vm = require('node:vm');
const template = readFileSync(`${__dirname}/../templates/admin/v2.html`, 'utf8');
const script = template.match(/<script>\s*(function adminV2\(\)[\s\S]*?)<\/script>/)[1];
const ui = readFileSync(`${__dirname}/../templates/admin/ui.html`, 'utf8').match(/<script>([\s\S]*?)<\/script>/)[1];
const script = ui + '\n' + template.match(/<script>\s*(function adminV2\(\)[\s\S]*?)<\/script>/)[1];
function createApp() {
const context = vm.createContext({});
+164
View File
@@ -0,0 +1,164 @@
// Run against a disposable local instance with at least one admin and one release.
// Existing data is read only; long-content fixtures are injected into browser state.
// FURU_TEST_URL, FURU_TEST_USERNAME, FURU_TEST_PASSWORD, PLAYWRIGHT_MODULE,
// CHROME_PATH and FURU_TEST_SCREENSHOTS configure the runner.
const assert = require('node:assert/strict');
const {chromium} = require(process.env.PLAYWRIGHT_MODULE || 'playwright');
const {mkdirSync} = require('node:fs');
const base = process.env.FURU_TEST_URL || 'http://127.0.0.1:18048';
(async () => {
const browser = await chromium.launch({headless:true, executablePath:process.env.CHROME_PATH});
try {
const context = await browser.newContext({viewport:{width:390,height:844}, reducedMotion:'reduce'});
const response = await context.request.post(base+'/login', {form:{username:process.env.FURU_TEST_USERNAME || 'access-admin', password:process.env.FURU_TEST_PASSWORD || 'access-test-password'}});
assert.ok(response.ok());
const page = await context.newPage();
const errors = []; page.on('pageerror', error => errors.push(error.message));
await page.goto(base+'/admin/v2');
await page.waitForFunction(() => window.Alpine && document.querySelector('.admin-shell')._x_dataStack);
const state = (fn, arg) => page.evaluate(({code,arg}) => Function('app','arg',`return (${code})(app,arg)`)(Alpine.$data(document.querySelector('.admin-shell')), arg), {code:fn.toString(),arg});
await state(async app => { clearInterval(app.poller); await app.refreshAll(); });
const screenshot = async name => {
if (!process.env.FURU_TEST_SCREENSHOTS) return;
mkdirSync(process.env.FURU_TEST_SCREENSHOTS, {recursive:true});
await page.screenshot({path:process.env.FURU_TEST_SCREENSHOTS+'/'+name+'.png'});
};
async function fits(label) {
const overflow = await page.evaluate(() => [...document.querySelectorAll('html, body, main, .content, .panel, .modal, .modal-body')]
.filter(el => el.getClientRects().length && el.scrollWidth > el.clientWidth + 2)
.map(el => `${el.tagName}.${el.className}: ${el.scrollWidth} > ${el.clientWidth}`));
assert.deepEqual(overflow, [], label);
}
async function settle() { await page.waitForTimeout(200); }
async function navigate(view) {
if (await page.locator('.menu-toggle').isVisible()) await page.locator('.menu-toggle').click();
await page.locator('.nav-btn').filter({hasText:{reviews:'Review Queue',jobs:'Tasks',library:'Library Workbench',tools:'Library Tools',statistics:'Statistics',users:'Users',settings:'Settings'}[view]}).click();
await page.waitForFunction(v => Alpine.$data(document.querySelector('.admin-shell')).activeView === v, view);
await settle();
assert.equal(await page.locator('main').evaluate(el => el.inert), false);
}
// Navigate through the actual menu, testing both permanent and drawer modes.
for (const width of [320,390,768,1024,1440]) {
await page.setViewportSize({width,height:844}); await settle();
for (const view of ['reviews','jobs','library','tools','statistics','users','settings']) {
await navigate(view); await fits(`${width}: ${view}`);
if (width === 390 || width === 1440) await screenshot(`${width}-${view}`);
}
}
await page.setViewportSize({width:390,height:844}); await settle();
await page.locator('.menu-toggle').click(); await settle();
assert.equal(await page.locator('main').evaluate(el => el.inert), true);
await screenshot('390-navigation');
await page.keyboard.press('Shift+Tab');
assert.equal(await page.evaluate(() => document.activeElement.classList.contains('nav-player')), true);
await page.keyboard.press('Tab');
assert.equal(await page.evaluate(() => document.activeElement.hasAttribute('data-dialog-close')), true);
await page.keyboard.press('Escape'); await settle();
assert.equal(await page.evaluate(() => document.activeElement.classList.contains('menu-toggle')), true);
await page.locator('.menu-toggle').click(); await page.setViewportSize({width:1440,height:844}); await settle();
assert.equal(await page.locator('main').evaluate(el => el.inert), false);
assert.equal(await page.locator('.sidebar').evaluate(el => el.inert), false);
await page.setViewportSize({width:390,height:844}); await settle();
await navigate('jobs');
await page.locator('#task-pane-list tbody tr').first().click(); await settle();
assert.equal(await page.locator('#task-pane-list').isVisible(), false);
assert.equal(await page.locator('#task-pane-details').isVisible(), true);
await page.getByRole('button', {name:'Edit schedule',exact:true}).click();
await page.getByRole('textbox', {name:'Cron schedule'}).fill('0 15 * * * *');
await page.locator('#task-tab-logs').click();
await page.keyboard.press('ArrowLeft');
assert.equal(await page.getByRole('textbox', {name:'Cron schedule'}).inputValue(), '0 15 * * * *');
await fits('task editor');
await navigate('settings');
await page.locator('.section-jump select').selectOption('federation'); await settle();
assert.equal(await page.evaluate(() => document.activeElement.id), 'settings-federation');
await page.getByRole('button',{name:'Save settings',exact:true}).scrollIntoViewIfNeeded();
await fits('settings footer');
// Shared dialog lifecycle: trap focus, lock background, retain close affordance,
// scroll long content and restore focus to its trigger.
async function checkDialog(name) {
const dialog = page.locator('.modal:visible'); await dialog.waitFor(); await settle();
assert.equal(await page.locator('main').evaluate(el => el.inert), true);
await fits(name);
assert.ok((await dialog.locator('.modal-body').innerText()).trim().length > 0, name+' body populated');
const box = await dialog.boundingBox();
if (page.viewportSize().width < 768) assert.ok(Math.abs(box.height-page.viewportSize().height)<2, name+' full height');
await dialog.focus(); await page.keyboard.press('Shift+Tab');
assert.equal(await dialog.evaluate(el => el.contains(document.activeElement)), true);
await page.keyboard.press('Tab');
assert.equal(await page.evaluate(() => document.activeElement.hasAttribute('data-dialog-close')), true);
await screenshot(name);
await dialog.locator('.modal-body').evaluate(el => { el.scrollTop=el.scrollHeight; });
await fits(name+' bottom');
const close = await dialog.locator('[data-dialog-close]').boundingBox();
assert.ok(close.y >= 0 && close.y+close.height <= page.viewportSize().height, name+' close reachable');
const footer = dialog.locator('.dialog-actions:visible');
if (await footer.count()) {
const bottom = await footer.boundingBox();
assert.ok(bottom.y >= -1 && bottom.y+bottom.height <= page.viewportSize().height+1, name+' actions reachable');
}
await page.keyboard.press('Escape'); await settle();
assert.equal(await page.locator('.modal:visible').count(),0);
assert.equal(await page.locator('main').evaluate(el => el.inert),false);
}
await navigate('users');
await page.getByRole('button',{name:'Add user',exact:true}).click();
await checkDialog('390-add-user');
assert.equal(await page.evaluate(() => document.activeElement.textContent.trim()), 'Add user');
await page.locator('.users-table tbody tr').first().click();
await checkDialog('390-user-profile');
const review = {id:987654,status:'pending',review_type:'metadata',filename:'Very long track title '.repeat(8),display_path:'/inbox/'+'album/'.repeat(20),tags:[],normalized:{title:'Long song title',artist:'Test artist',notes:'Notes\n'.repeat(40)}};
await navigate('reviews');
await state((app,row) => {app.reviews.items=[row]; app.reviews.total=1; app.openReview(row);}, review);
await checkDialog('390-review');
await fits('populated reviews');
await navigate('library');
await state(async app => {app.libraryKind='releases'; await app.loadLibrary(); app.openEditor(app.library.items[0]);});
await page.waitForFunction(() => !Alpine.$data(document.querySelector('.admin-shell')).editorLoading);
await state(app => {app.editorDraft.release_tracks = Array.from({length:12}, (_,i)=>({...app.editorDraft.release_tracks[0],id:700000+i,title:'Very long track title '.repeat(8),disc_number:1,track_number:i+1}));});
await page.locator('.modal:visible input[x-model="editorDraft.title"]').waitFor({state:'visible'});
assert.equal(await page.locator('.modal:visible .release-track-row:visible').count(),12);
await checkDialog('390-release-editor');
await state(app => {
const detail = app.editorDetail;
app.mergeDetails=[detail,{...detail,item:{...detail.item,id:700001},title:'Second release'}];
app.mergeDraft={release_ids:[detail.item.id,700001],target_release_id:detail.item.id,title:detail.title,release_type:'album',hidden:'false',year:'2026',artist_ids:[],cover_file_id:null,tracks:app.editorDraft.release_tracks};
app.mergeOpen=true;
});
await checkDialog('390-merge');
// Short landscape viewport and desktop dialog geometry use the same contract.
for (const viewport of [{width:320,height:568},{width:844,height:390},{width:1440,height:900}]) {
await page.setViewportSize(viewport); await settle();
await state((app,row)=>app.openReview(row),review);
await checkDialog(`${viewport.width}-review`);
}
await page.setViewportSize({width:320,height:700}); await settle();
await navigate('statistics');
await state(async app => {
await app.loadStatistics();
app.statisticsData.ranking.items=[{key:'fixture',label:'Very long artist name '.repeat(12),detail:'long_identifier_'.repeat(20),plays:42,listeners:10,listened_seconds:10000,last_play_ms:Date.now()}];
app.statisticsData.history.items=[{user_id:1,listen_id:'fixture',user_name:'Listener '.repeat(12),title:'Long song name '.repeat(12),content_id:'fixture',artist_names:['Artist '.repeat(20)],release_title:'Album '.repeat(20),started_at_ms:Date.now(),listened_ms:60000,track_duration_ms:90000,qualified:true,ended_reason:'ended',device_name:'LongDeviceName'.repeat(20),source:'instance'}];
});
await settle(); await fits('320 populated statistics');
await navigate('tools');
await state(app => {
app.repairExpanded={snapshot:{artists:[{id:1,name:'Artist'}],releases:[{id:2,title:'Album',year:2026,release_type:'album',artist_ids:[1]}],tracks:[]}};
app.repairPlan={artists:[],releases:[{id:2,title:'Album '.repeat(30),year:2026,release_type:'album',artist_ids:[1]}],tracks:[],questions:[],delete:{artists:[],releases:[],tracks:[]}};
app.repairPlanOpen=true;
});
await page.locator('.repair-manual summary').click(); await settle();
await fits('320 manual metadata comparison');
const comparison=page.locator('.repair-manual');
assert.ok(await comparison.evaluate(el=>el.scrollWidth>el.clientWidth), 'wide comparison scrolls within its own region');
await screenshot('320-manual-comparison');
await navigate('users');
await page.locator('.users-table tbody tr').first().click();
await page.getByRole('button',{name:'Edit user',exact:true}).click();
await checkDialog('320-edit-user');
await page.locator('.menu-toggle').click();
await page.goBack(); await settle();
assert.equal(await page.locator('main').evaluate(el=>el.inert),false, 'browser Back closes navigation');
assert.deepEqual(errors, []);
console.log('PASS: 7 sections × 5 widths; drawer, task tabs, settings jump and all 5 dialogs, keyboard and long content.');
} finally { await browser.close(); }
})().catch(error => {console.error(error); process.exitCode=1;});