From bd44f8306c9129b9420ad81938bcf8105a1cb55a Mon Sep 17 00:00:00 2001 From: Caleb Allen Date: Thu, 12 Mar 2026 19:37:07 -0400 Subject: [PATCH] feat(12-01): implement library CRUD methods and orphan cleanup pipeline MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add AddLibrary, RenameLibrary, RemoveLibrary, GetRemovalImpact methods - RemoveLibrary follows exact order: phantom populate → delete audio_files → orphan cleanup → commit → FTS5 rebuild → cover art file cleanup → queue compact → events - Add cancelLibraryScan and currentTrackBelongsToLibrary helpers - Add RemovalHooks type and removalHooks field on Library struct - Add LibraryAdded, LibraryRenamed, LibraryRemoved event constants - Regenerate frontend events.ts with new CRUD events - All hand-crafted SQL has SAFETY comments per project convention - Dual artist_credit FK check (recordings + release_groups) for orphan cleanup --- backend/events/events.go | 7 + backend/library/crud.go | 525 +++++++++++++++++++++++++++++++++++++ backend/library/library.go | 4 + frontend/src/events.ts | 5 + 4 files changed, 541 insertions(+) create mode 100644 backend/library/crud.go diff --git a/backend/events/events.go b/backend/events/events.go index 2c8ae23..4872ad0 100644 --- a/backend/events/events.go +++ b/backend/events/events.go @@ -60,3 +60,10 @@ const ( LibraryScanQueued = "LibraryScanQueued" LibraryScanQueueDrained = "LibraryScanQueueDrained" ) + +// Library CRUD events. +const ( + LibraryAdded = "LibraryAdded" + LibraryRenamed = "LibraryRenamed" + LibraryRemoved = "LibraryRemoved" +) diff --git a/backend/library/crud.go b/backend/library/crud.go new file mode 100644 index 0000000..0a34504 --- /dev/null +++ b/backend/library/crud.go @@ -0,0 +1,525 @@ +package library + +import ( + "context" + "errors" + "fmt" + "os" + "path/filepath" + "strings" + + "github.com/wailsapp/wails/v2/pkg/runtime" + + "yellowjacket/backend/database" + "yellowjacket/backend/database/sql/sqlcgen" + "yellowjacket/backend/events" +) + +// Sentinel errors for library CRUD validation. +var ( + errLibraryNameEmpty = errors.New("library name must not be empty") + errLibraryNameTooLong = errors.New("library name must be 50 characters or fewer") + errLibraryNameDuplicate = errors.New("a library with that name already exists") + errLibraryPathNotExist = errors.New("directory does not exist") + errQueryNoRows = errors.New("query returned no rows") +) + +// maxLibraryNameLength is the maximum number of characters allowed +// in a library display name. +const maxLibraryNameLength = 50 + +// RemovalHooks contains callbacks invoked during library removal. +// These break circular dependencies between the library, player, +// and queue packages. +type RemovalHooks struct { + // StopPlayback stops the currently-playing track. + StopPlayback func() + // CompactQueue reloads queue state after cascade deletes. + CompactQueue func() +} + +// SetRemovalHooks provides optional hooks for cross-cutting +// orchestration during RemoveLibrary. +func (l *Library) SetRemovalHooks(h RemovalHooks) { + l.mu.Lock() + defer l.mu.Unlock() + + l.removalHooks = h +} + +// RemovalImpact contains pre-removal counts for the confirmation dialog. +type RemovalImpact struct { + TrackCount int64 `json:"trackCount"` + PlaylistsAffected int64 `json:"playlistsAffected"` + QueueItemCount int64 `json:"queueItemCount"` +} + +// RemovalSummary contains post-removal counts for the toast notification. +type RemovalSummary struct { + TracksDeleted int64 `json:"tracksDeleted"` + ArtistsRemoved int64 `json:"artistsRemoved"` + AlbumsRemoved int64 `json:"albumsRemoved"` + GenresRemoved int64 `json:"genresRemoved"` + PlaylistsAffected int64 `json:"playlistsAffected"` + QueueItemsRemoved int64 `json:"queueItemsRemoved"` +} + +// AddLibrary creates a new library from a directory path, emits a +// LibraryAdded event, and starts an asynchronous scan. +func (l *Library) AddLibrary(path string) (*sqlcgen.Library, error) { + if _, err := os.Stat(path); err != nil { + return nil, fmt.Errorf("%w: %s", errLibraryPathNotExist, path) + } + + name := filepath.Base(path) + + lib, err := l.db.Queries.CreateLibrary(l.ctx, sqlcgen.CreateLibraryParams{ + Name: name, + Path: path, + }) + if err != nil { + return nil, fmt.Errorf("could not create library: %w", err) + } + + runtime.EventsEmit(l.ctx, events.LibraryAdded, lib) + + go func() { + if scanErr := l.ScanLibrary(lib.ID); scanErr != nil { + l.logger.Error("auto-scan after add failed", + "libraryID", lib.ID, + "err", scanErr, + ) + } + }() + + return &lib, nil +} + +// RenameLibrary validates and updates a library's display name. +func (l *Library) RenameLibrary(id int64, newName string) error { + newName = strings.TrimSpace(newName) + + if newName == "" { + return errLibraryNameEmpty + } + + if len(newName) > maxLibraryNameLength { + return errLibraryNameTooLong + } + + // Application-level uniqueness check (no schema migration needed). + libs, err := l.db.Queries.GetAllLibraries(l.ctx) + if err != nil { + return fmt.Errorf("could not check existing names: %w", err) + } + + for _, lib := range libs { + if lib.ID != id && lib.Name == newName { + return fmt.Errorf("%w: %q", errLibraryNameDuplicate, newName) + } + } + + if err := l.db.Queries.UpdateLibraryName(l.ctx, sqlcgen.UpdateLibraryNameParams{ + Name: newName, + ID: id, + }); err != nil { + return fmt.Errorf("could not rename library: %w", err) + } + + runtime.EventsEmit(l.ctx, events.LibraryRenamed, map[string]any{ + "id": id, + "name": newName, + }) + + return nil +} + +// GetRemovalImpact returns pre-removal counts for the confirmation +// dialog. All queries are read-only. +func (l *Library) GetRemovalImpact(libraryID int64) (*RemovalImpact, error) { + // SAFETY: Hand-crafted SQL for track count. sqlc query CountAudioFilesByLibrary + // exists but we inline the remaining two for consistency. Parameterized. + trackCount, err := l.db.Queries.CountAudioFilesByLibrary(l.ctx, libraryID) + if err != nil { + return nil, fmt.Errorf("could not count tracks: %w", err) + } + + // SAFETY: Hand-crafted SQL for playlists affected by library removal. + // Multi-table JOIN with DISTINCT unsupported by sqlc. Parameterized. + playlistsAffected, err := querySingleInt64(l.ctx, l.db, + `SELECT COUNT(DISTINCT pt.playlist_id) + FROM playlist_tracks pt + JOIN audio_files af ON pt.audio_file_id = af.id + WHERE af.library_id = ?`, + libraryID, + ) + if err != nil { + return nil, fmt.Errorf("could not count affected playlists: %w", err) + } + + // SAFETY: Hand-crafted SQL for queue items affected by library removal. + // Multi-table JOIN unsupported by sqlc. Parameterized. + queueItemCount, err := querySingleInt64(l.ctx, l.db, + `SELECT COUNT(*) + FROM queue_tracks qt + JOIN audio_files af ON qt.audio_file_id = af.id + WHERE af.library_id = ?`, + libraryID, + ) + if err != nil { + return nil, fmt.Errorf("could not count queue items: %w", err) + } + + return &RemovalImpact{ + TrackCount: trackCount, + PlaylistsAffected: playlistsAffected, + QueueItemCount: queueItemCount, + }, nil +} + +// RemoveLibrary atomically removes a library and all its data, +// performing orphan cleanup, phantom metadata conversion, FTS5 +// rebuild, and queue compaction. Returns a summary of what was removed. +func (l *Library) RemoveLibrary(id int64) (*RemovalSummary, error) { + // 1. Cancel active scan for this library. + l.cancelLibraryScan(id) + + // 2. Stop playback if the currently-playing track belongs to this library. + if l.currentTrackBelongsToLibrary(id) { + if l.removalHooks.StopPlayback != nil { + l.removalHooks.StopPlayback() + } + } + + // 3. Pre-count for summary. + impact, err := l.GetRemovalImpact(id) + if err != nil { + return nil, fmt.Errorf("could not get removal impact: %w", err) + } + + // 4. Begin transaction. + tx, err := l.db.BeginTx() + if err != nil { + return nil, fmt.Errorf("could not begin transaction: %w", err) + } + + committed := false + + defer func() { + if !committed { + _ = tx.Rollback() + } + }() + + // 5. Populate phantom metadata BEFORE deleting audio_files. + // SAFETY: Hand-crafted UPDATE-FROM-SELECT for phantom metadata population. + // Must run BEFORE DELETE FROM audio_files (which triggers SET NULL on + // playlist_tracks.audio_file_id). Multi-table JOIN with subqueries + // unsupported by sqlc. All values parameterized. + if _, err := tx.ExecContext(l.ctx, ` + UPDATE playlist_tracks SET + phantom_title = sub.title, + phantom_artist = sub.artist, + phantom_album = sub.album, + phantom_duration_ms = sub.duration, + phantom_genre = sub.genre, + phantom_cover_art_path = sub.cover_art_path + FROM ( + SELECT + pt.id AS pt_id, + COALESCE(r.name, '') AS title, + COALESCE(ac.text, '') AS artist, + COALESCE(rg.name, '') AS album, + af.length_milliseconds AS duration, + CAST(COALESCE( + (SELECT GROUP_CONCAT(g.name, '||') + FROM recording_genres rg_sub + JOIN genres g ON rg_sub.genre_id = g.id + WHERE rg_sub.recording_id = r.id), + '' + ) AS TEXT) AS genre, + COALESCE(ca.file_path, '') AS cover_art_path + FROM playlist_tracks pt + JOIN audio_files af ON pt.audio_file_id = af.id + LEFT JOIN recordings r ON af.recording_id = r.id + LEFT JOIN artist_credit ac ON r.artist_credit_id = ac.id + LEFT JOIN ( + SELECT recording_id, MIN(release_group_id) AS release_group_id + FROM release_group_recordings + GROUP BY recording_id + ) rgr ON r.id = rgr.recording_id + LEFT JOIN release_groups rg ON rgr.release_group_id = rg.id + LEFT JOIN cover_art ca ON rg.cover_art_id = ca.id + WHERE af.library_id = ? + ) sub + WHERE playlist_tracks.id = sub.pt_id`, id); err != nil { + return nil, fmt.Errorf("could not populate phantom metadata: %w", err) + } + + // 6. Delete audio_files (CASCADE deletes queue_tracks, SET NULL on playlist_tracks). + // SAFETY: Hand-crafted DELETE for bulk removal by library_id. + // sqlc DeleteAudioFile only handles single-row deletes. Parameterized. + result, err := tx.ExecContext(l.ctx, + `DELETE FROM audio_files WHERE library_id = ?`, id) + if err != nil { + return nil, fmt.Errorf("could not delete audio files: %w", err) + } + + tracksDeleted, _ := result.RowsAffected() + + // 7. Delete orphaned recordings. + // SAFETY: Hand-crafted orphan cleanup SQL. Reference-counting delete + // with NOT IN subquery unsupported by sqlc. No user input. + if _, err := tx.ExecContext(l.ctx, + `DELETE FROM recordings WHERE id NOT IN ( + SELECT DISTINCT recording_id FROM audio_files + )`); err != nil { + return nil, fmt.Errorf("could not delete orphaned recordings: %w", err) + } + + // 8. Delete orphaned recording_genres. + // SAFETY: Hand-crafted orphan cleanup SQL. Parameterless. + if _, err := tx.ExecContext(l.ctx, + `DELETE FROM recording_genres WHERE recording_id NOT IN ( + SELECT id FROM recordings + )`); err != nil { + return nil, fmt.Errorf("could not delete orphaned recording_genres: %w", err) + } + + // 9. Delete orphaned release_group_recordings. + // SAFETY: Hand-crafted orphan cleanup SQL. Parameterless. + if _, err := tx.ExecContext(l.ctx, + `DELETE FROM release_group_recordings WHERE recording_id NOT IN ( + SELECT id FROM recordings + )`); err != nil { + return nil, fmt.Errorf("could not delete orphaned release_group_recordings: %w", err) + } + + // 10. Delete orphaned release_groups. + // SAFETY: Hand-crafted orphan cleanup SQL. Parameterless. + result, err = tx.ExecContext(l.ctx, + `DELETE FROM release_groups WHERE id NOT IN ( + SELECT DISTINCT release_group_id FROM release_group_recordings + )`) + if err != nil { + return nil, fmt.Errorf("could not delete orphaned release_groups: %w", err) + } + + albumsRemoved, _ := result.RowsAffected() + + // 11. Delete orphaned artist_credits — CRITICAL: check BOTH recordings AND release_groups. + // SAFETY: Hand-crafted orphan cleanup SQL. Dual-FK reference counting + // (recordings.artist_credit_id + release_groups.album_artist_credit_id) + // unsupported by sqlc. Parameterless. + if _, err := tx.ExecContext(l.ctx, + `DELETE FROM artist_credit WHERE id NOT IN ( + SELECT DISTINCT artist_credit_id FROM recordings + ) AND id NOT IN ( + SELECT DISTINCT album_artist_credit_id FROM release_groups + WHERE album_artist_credit_id IS NOT NULL + )`); err != nil { + return nil, fmt.Errorf("could not delete orphaned artist_credits: %w", err) + } + + // 12. Delete orphaned artist_credit_artists. + // SAFETY: Hand-crafted orphan cleanup SQL. Parameterless. + if _, err := tx.ExecContext(l.ctx, + `DELETE FROM artist_credit_artist WHERE credit_id NOT IN ( + SELECT id FROM artist_credit + )`); err != nil { + return nil, fmt.Errorf("could not delete orphaned artist_credit_artists: %w", err) + } + + // 13. Delete orphaned artists. + // SAFETY: Hand-crafted orphan cleanup SQL. Parameterless. + result, err = tx.ExecContext(l.ctx, + `DELETE FROM artists WHERE id NOT IN ( + SELECT DISTINCT artist_id FROM artist_credit_artist + )`) + if err != nil { + return nil, fmt.Errorf("could not delete orphaned artists: %w", err) + } + + artistsRemoved, _ := result.RowsAffected() + + // 14. Delete orphaned genres. + // SAFETY: Hand-crafted orphan cleanup SQL. Parameterless. + result, err = tx.ExecContext(l.ctx, + `DELETE FROM genres WHERE id NOT IN ( + SELECT DISTINCT genre_id FROM recording_genres + )`) + if err != nil { + return nil, fmt.Errorf("could not delete orphaned genres: %w", err) + } + + genresRemoved, _ := result.RowsAffected() + + // 15. Collect orphaned cover_art file paths for post-commit cleanup. + // SAFETY: Hand-crafted SELECT for orphaned cover art identification. + // Parameterless. + rows, err := tx.QueryContext(l.ctx, + `SELECT file_path FROM cover_art WHERE id NOT IN ( + SELECT DISTINCT cover_art_id FROM release_groups + WHERE cover_art_id IS NOT NULL + )`) + if err != nil { + return nil, fmt.Errorf("could not query orphaned cover art: %w", err) + } + + var orphanedCoverArtPaths []string + + for rows.Next() { + var filePath string + if err := rows.Scan(&filePath); err != nil { + l.logger.Warn("could not scan cover art path", "err", err) + + continue + } + + orphanedCoverArtPaths = append(orphanedCoverArtPaths, filePath) + } + + if err := rows.Close(); err != nil { + l.logger.Warn("could not close cover art rows", "err", err) + } + + // 16. Delete orphaned cover_art rows. + // SAFETY: Hand-crafted orphan cleanup SQL. Parameterless. + if _, err := tx.ExecContext(l.ctx, + `DELETE FROM cover_art WHERE id NOT IN ( + SELECT DISTINCT cover_art_id FROM release_groups + WHERE cover_art_id IS NOT NULL + )`); err != nil { + return nil, fmt.Errorf("could not delete orphaned cover_art: %w", err) + } + + // 17. Delete library row. + // SAFETY: Hand-crafted DELETE matching sqlc DeleteLibrary but within + // the same transaction. Parameterized. + if _, err := tx.ExecContext(l.ctx, + `DELETE FROM libraries WHERE id = ?`, id); err != nil { + return nil, fmt.Errorf("could not delete library: %w", err) + } + + // 18. Commit transaction. + if err := tx.Commit(); err != nil { + return nil, fmt.Errorf("could not commit removal transaction: %w", err) + } + + committed = true + + // 19. Post-commit: Rebuild FTS5 (cannot run inside transaction). + if err := l.db.RebuildSearchIndex(); err != nil { + l.logger.Error("could not rebuild search index after removal", "err", err) + } + + // 20. Post-commit: Delete orphaned cover art files. + for _, coverPath := range orphanedCoverArtPaths { + if err := os.Remove(coverPath); err != nil && !os.IsNotExist(err) { + l.logger.Warn("could not remove orphaned cover art file", + "path", coverPath, + "err", err, + ) + } + } + + // 21. Post-commit: Compact queue. + if l.removalHooks.CompactQueue != nil { + l.removalHooks.CompactQueue() + } + + summary := &RemovalSummary{ + TracksDeleted: tracksDeleted, + ArtistsRemoved: artistsRemoved, + AlbumsRemoved: albumsRemoved, + GenresRemoved: genresRemoved, + PlaylistsAffected: impact.PlaylistsAffected, + QueueItemsRemoved: impact.QueueItemCount, + } + + // 22. Emit events. + runtime.EventsEmit(l.ctx, events.LibraryRemoved, map[string]any{ + "id": id, + "summary": summary, + }) + + return summary, nil +} + +// cancelLibraryScan cancels an active scan for the specified library +// and removes it from the scan queue. +func (l *Library) cancelLibraryScan(id int64) { + l.mu.Lock() + defer l.mu.Unlock() + + // If this library is currently scanning, cancel it. + if l.currentScanLibraryID == id { + if l.scanCancel != nil { + l.scanCancel() + } + } + + // Remove from the scan queue if queued. + filtered := l.scanQueue[:0] + + for _, entry := range l.scanQueue { + if entry.libraryID != id { + filtered = append(filtered, entry) + } + } + + l.scanQueue = filtered +} + +// currentTrackBelongsToLibrary checks whether the currently-playing +// queue track belongs to the specified library. +func (l *Library) currentTrackBelongsToLibrary(libraryID int64) bool { + // SAFETY: Hand-crafted SQL to check if the current queue track belongs + // to the library being removed. Multi-table JOIN with subquery + // unsupported by sqlc. Parameterized. + count, err := querySingleInt64(l.ctx, l.db, + `SELECT COUNT(*) FROM audio_files af + JOIN queue_tracks qt ON qt.audio_file_id = af.id + WHERE af.library_id = ? + AND qt.position = ( + SELECT current_position FROM queue LIMIT 1 + )`, + libraryID, + ) + if err != nil { + l.logger.Warn("could not check if current track belongs to library", + "libraryID", libraryID, + "err", err, + ) + + return false + } + + return count > 0 +} + +// querySingleInt64 executes a query that returns a single integer value. +func querySingleInt64( + _ context.Context, + db *database.DB, + query string, + args ...any, +) (int64, error) { + rows, err := db.QueryContext(query, args...) + if err != nil { + return 0, err + } + + defer func() { _ = rows.Close() }() + + if !rows.Next() { + return 0, errQueryNoRows + } + + var val int64 + if err := rows.Scan(&val); err != nil { + return 0, err + } + + return val, rows.Err() +} diff --git a/backend/library/library.go b/backend/library/library.go index 00ff12f..3a93804 100644 --- a/backend/library/library.go +++ b/backend/library/library.go @@ -93,6 +93,10 @@ type Library struct { scanQueue []scanQueueEntry currentScanLibraryID int64 currentScanLibraryName string + + // removalHooks holds callbacks for cross-cutting concerns during + // library removal (e.g. stopping playback, compacting queue). + removalHooks RemovalHooks } // SetRescanHooks provides optional hooks for cross-cutting diff --git a/frontend/src/events.ts b/frontend/src/events.ts index 7890c9c..809ecd7 100644 --- a/frontend/src/events.ts +++ b/frontend/src/events.ts @@ -42,6 +42,11 @@ export const Events = { // Scan queue events LibraryScanQueued: "LibraryScanQueued", LibraryScanQueueDrained: "LibraryScanQueueDrained", + + // Library CRUD events + LibraryAdded: "LibraryAdded", + LibraryRenamed: "LibraryRenamed", + LibraryRemoved: "LibraryRemoved", } as const; export type EventName = (typeof Events)[keyof typeof Events];