feat(vps): port music albums/tracks/playlists CRUD (Step 6c)

[guidefari]

Why

Fixes a live production regression: /api/music/albums, /api/music/tracks, and /api/music/playlists have been 404ing since commit d052ce82 ("port search to HttpApiBuilder.group, Step 6"), which deleted routes/music/* claiming the code was "dead Hono code... already superseded" by http/music.handlers.ts. That claim was false — the new Effect handler only ever implemented artist CRUD + artist-junction endpoints, never albums/tracks/playlists. This has been breaking apps/www's admin UI (useAdminAlbums/useAdminTracks in routes/admin/music.tsx) since that commit landed.

Flagged as tracked follow-up in docs/migration-effect-http-api.md after the Hono-removal PR (#190); this PR resolves it.

What

Extends the existing music HttpApiGroup (packages/api/src/music.ts) and MusicHandlersLive (apps/vps/src/http/music.handlers.ts) with:

• Album CRUD (list/get/create/update/delete)
• Track CRUD (list/get/create/update/delete)
• Playlist CRUD (list/get/create/update/delete)
• Playlist-tracks management (list tracks, add, remove, reorder)
• Spotify integration (add-track-by-URL, import-playlist [fire-and-forget via runAppFork], sync-links)

All backed by the existing, already-wired MusicEntityService — no service-layer changes, pure route-layer work.

Deliberately out of scope (separate stacked PR to follow): entity-links CRUD, resolveMusicEntity, scrapeEntityLinks, listPendingLinks. These are a distinct concern (link-review workflow vs entity CRUD) with their own real apps/www consumers (useAdminEntityLinks, useResolveMusicEntity in -MusicEntityDetailPage.tsx/-TweetCapturePage.tsx).

Admin-role enforcement follows the same convention as the already-merged artist group in this file: AuthMiddleware only requires login; requireAdmin inside the handler returns Forbidden for non-admins, keeping the schema layer's declared error union honest without a hard admin gate baked into middleware.

Test evidence

Blackbox tests (18 new, all passing against a real ephemeral Postgres — 102/102 total in the file):

$ bun vitest run src/http/routes.blackbox.test.ts
 Test Files  1 passed (1)
      Tests  102 passed (102)

Live curl verification against dev server with real data:

$ curl -s http://localhost:3003/api/music/albums | head -c 300
[{"id":"7a0fea96-...","title":"Konnichiwa","artistNames":["Skepta"],"releaseDate":null,
  "coverImageUrl":"https://cdn.goosebumps.fm/...","genres":null,"albumType":null,
  "slug":"konnichiwa-18a11cb6",...}]

$ curl -s -o /dev/null -w "%{http_code}\n" http://localhost:3003/api/music/tracks
200
$ curl -s -o /dev/null -w "%{http_code}\n" http://localhost:3003/api/music/playlists
200
$ curl -s -o /dev/null -w "%{http_code}\n" http://localhost:3003/api/music/albums/00000000-0000-0000-0000-000000000000
404
$ curl -s -o /dev/null -w "%{http_code}\n" -X POST http://localhost:3003/api/music/albums -d '{"title":"x","slug":"x"}'
401

Response shape matches apps/www's existing MusicAlbum/MusicTrack interfaces (apps/www/src/lib/http.ts) field-for-field, so the existing useAdminAlbums/useAdminTracks hooks (plain fetcher(apiUrl(...)), not the typed client) work against this without any www-side changes.

I attempted a full browser screenshot of the admin UI but couldn't get past the admin-role auth gate without either a known admin credential or writing a role grant to an unconfirmed database — declined to guess/bypass either, so this PR ships with API-contract-level evidence (curl + blackbox tests) rather than a UI screenshot. The UI code itself is unchanged by this PR; only the backend contract it already expects is being restored.

Test plan

• bun run typecheck clean (packages/api, apps/vps, apps/www)
• bun precommit clean (format, lint, typecheck)
• 18 new blackbox tests, 102/102 passing
• Live curl verification of all new GET/POST/PATCH/DELETE routes against dev server with real data
• Auth gating verified (401 for all admin-mutation routes without session)

[guidefari]

Addressed 3 findings from adversarial review (commit ff48fa0):

1. addSpotifyTrackToPlaylist swallowed a client-fixable 400 as a 500 — a bad Spotify track URL now correctly maps to HttpApiError.BadRequest, matching the sibling importSpotifyPlaylist handler's existing behavior for the same failure.
2. UpdateAlbumInput/UpdateTrackInput/UpdatePlaylistInput rejected null — the admin edit forms submit full form state (not a diff) on every save, so an unset field arrives as null, not absent. Every optional field now accepts null in addition to the value/absent cases. Reproduced and pinned with a decoder test in packages/api/src/music.test.ts.
3. CreateAlbumInput/CreateTrackInput/CreatePlaylistInput accepted an empty title/slug — a plain Schema.String let '' through to a NOT NULL varchar column, unlike the old Zod schemas' .min(1). Fixed with a shared NonEmptyString check, also pinned with a test. Also restored .url()-equivalent validation on the two Spotify URL input fields that had silently dropped it.

Full blackbox suite (102/102) and the new music.test.ts (6/6) pass. bun precommit clean.

[github-actions]

🎉 This PR is included in version 2.66.0 🎉

The release is available on GitHub release

Your semantic-release bot 📦🚀