refactor: shared behavioral interfaces for media domains (handler & repo layer)

cmd/commands.go

···
 Use the -i flag for an interactive interface with navigation keys.`,
 		RunE: func(cmd *cobra.Command, args []string) error {
 			interactive, _ := cmd.Flags().GetBool("interactive")
-			return c.handler.SearchAndAdd(cmd.Context(), args, interactive)
+			query := strings.Join(args, " ")
+			return c.handler.SearchAndAdd(cmd.Context(), query, interactive)
 		},
 	}
 	addCmd.Flags().BoolP("interactive", "i", false, "Use interactive interface for book selection")

internal/handlers/books.go

···
 )
 
 // BookHandler handles all book-related commands
+//
+// Implements MediaHandler interface for polymorphic media handling
 type BookHandler struct {
 	db      *store.Database
 	config  *store.Config
···
 	service *services.BookService
 	reader  io.Reader
 }
+
+// Ensure BookHandler implements MediaHandler interface
+var _ MediaHandler = (*BookHandler)(nil)
 
 // NewBookHandler creates a new book handler
 func NewBookHandler() (*BookHandler, error) {
···
 }
 
 // SearchAndAdd searches for books and allows user to select and add to queue
-func (h *BookHandler) SearchAndAdd(ctx context.Context, args []string, interactive bool) error {
-	if len(args) == 0 {
-		return fmt.Errorf("usage: book add <search query>")
-	}
-
-	query := args[0]
-	if len(args) > 1 {
-		for _, arg := range args[1:] {
-			query += " " + arg
-		}
+func (h *BookHandler) SearchAndAdd(ctx context.Context, query string, interactive bool) error {
+	if query == "" {
+		return fmt.Errorf("search query cannot be empty")
 	}
 
 	if interactive {
···
 	fmt.Println()
 	return nil
 }
+
+// Remove removes a book from the queue
+func (h *BookHandler) Remove(ctx context.Context, id string) error {
+	bookID, err := ParseID(id, "book")
+	if err != nil {
+		return err
+	}
+
+	book, err := h.repos.Books.Get(ctx, bookID)
+	if err != nil {
+		return fmt.Errorf("book %d not found: %w", bookID, err)
+	}
+
+	if err := h.repos.Books.Delete(ctx, bookID); err != nil {
+		return fmt.Errorf("failed to remove book: %w", err)
+	}
+
+	fmt.Printf("✓ Removed book: %s", book.Title)
+	if book.Author != "" {
+		fmt.Printf(" by %s", book.Author)
+	}
+	fmt.Println()
+
+	return nil
+}

internal/handlers/books_test.go

···
 			ctx := context.Background()
 			t.Run("fails with empty args", func(t *testing.T) {
 				args := []string{}
-				err := handler.SearchAndAdd(ctx, args, false)
+				query := strings.Join(args, " ")
+				err := handler.SearchAndAdd(ctx, query, false)
 				if err == nil {
 					t.Error("Expected error for empty args")
 				}
-
-				if !strings.Contains(err.Error(), "usage: book add") {
-					t.Errorf("Expected usage error, got: %v", err)
-				}
 			})
 
 			t.Run("context cancellation during search", func(t *testing.T) {
 				ctx, cancel := context.WithCancel(context.Background())
 				cancel()
-
-				if err := handler.SearchAndAdd(ctx, []string{"test", "book"}, false); err == nil {
+				query := strings.Join([]string{"test", "book"}, " ")
+				if err := handler.SearchAndAdd(ctx, query, false); err == nil {
 					t.Error("Expected error for cancelled context")
 				}
 			})
···
 
 				handler.service = services.NewBookService(mockServer.URL())
 
-				err := handler.SearchAndAdd(ctx, []string{"test", "book"}, false)
+				err := handler.SearchAndAdd(ctx, strings.Join([]string{"test", "book"}, " "), false)
 				if err == nil {
 					t.Error("Expected error for HTTP 500")
 				}
···
 
 				handler.service = services.NewBookService(mockServer.URL())
 
-				err := handler.SearchAndAdd(ctx, []string{"test", "book"}, false)
+				err := handler.SearchAndAdd(ctx, strings.Join([]string{"test", "book"}, " "), false)
 				if err == nil {
 					t.Error("Expected error for malformed JSON")
 				}
···
 				handler.service = services.NewBookService(mockServer.URL())
 
 				args := []string{"nonexistent", "book"}
-				err := handler.SearchAndAdd(ctx, args, false)
+				query := strings.Join(args, " ")
+				err := handler.SearchAndAdd(ctx, query, false)
 				if err != nil {
 					t.Errorf("Expected no error for empty results, got: %v", err)
 				}
···
 				ctx, cancel := context.WithTimeout(context.Background(), 100*time.Millisecond)
 				defer cancel()
 
-				if err := handler.SearchAndAdd(ctx, []string{"test", "book"}, false); err == nil {
+				if err := handler.SearchAndAdd(ctx, strings.Join([]string{"test", "book"}, " "), false); err == nil {
 					t.Error("Expected error for timeout")
 				}
 			})
···
 				ctx, cancel := context.WithCancel(context.Background())
 				cancel()
 
-				if err := handler.SearchAndAdd(ctx, []string{"test", "book"}, false); err == nil {
+				if err := handler.SearchAndAdd(ctx, strings.Join([]string{"test", "book"}, " "), false); err == nil {
 					t.Error("Expected error for cancelled context")
 				}
 			})
···
 				handler.SetInputReader(MenuSelection(1))
 
 				args := []string{"test", "search"}
-				err := handler.SearchAndAdd(ctx, args, false)
+				query := strings.Join(args, " ")
+				err := handler.SearchAndAdd(ctx, query, false)
 				if err != nil {
 					t.Errorf("Expected successful search and add, got error: %v", err)
 				}
···
 				handler.SetInputReader(MenuCancel())
 
 				args := []string{"another", "search"}
-				err := handler.SearchAndAdd(ctx, args, false)
+				query := strings.Join(args, " ")
+				err := handler.SearchAndAdd(ctx, query, false)
 				if err != nil {
 					t.Errorf("Expected no error on cancellation, got: %v", err)
 				}
···
 				handler.SetInputReader(MenuSelection(5))
 
 				args := []string{"choice", "test"}
-				err := handler.SearchAndAdd(ctx, args, false)
+				query := strings.Join(args, " ")
+				err := handler.SearchAndAdd(ctx, query, false)
 				if err == nil {
 					t.Error("Expected error for invalid choice")
 				}

internal/handlers/media_handler.go

···
+package handlers
+
+import (
+	"context"
+	"io"
+)
+
+// MediaHandler defines common operations for media handlers
+//
+// This interface captures the shared behavior across media handlers for polymorphic handling of different media types.
+type MediaHandler interface {
+	// SearchAndAdd searches for media and allows user to select and add to queue
+	SearchAndAdd(ctx context.Context, query string, interactive bool) error
+	// List lists all media items with optional status filtering
+	List(ctx context.Context, status string) error
+	// UpdateStatus changes the status of a media item
+	UpdateStatus(ctx context.Context, id, status string) error
+	// Remove removes a media item from the queue
+	Remove(ctx context.Context, id string) error
+	// SetInputReader sets the input reader for interactive prompts
+	SetInputReader(reader io.Reader)
+	// Close cleans up resources
+	Close() error
+}
+
+// Searchable defines search behavior for media handlers
+type Searchable interface {
+	SearchAndAdd(ctx context.Context, query string, interactive bool) error
+}
+
+// Listable defines list behavior for media handlers
+type Listable interface {
+	List(ctx context.Context, status string) error
+}
+
+// StatusUpdatable defines status update behavior for media handlers
+type StatusUpdatable interface {
+	UpdateStatus(ctx context.Context, id, status string) error
+}
+
+// Removable defines remove behavior for media handlers
+type Removable interface {
+	Remove(ctx context.Context, id string) error
+}

internal/handlers/media_utilities.go

···
+package handlers
+
+import (
+	"context"
+	"fmt"
+	"io"
+	"strconv"
+
+	"github.com/stormlightlabs/noteleaf/internal/models"
+)
+
+// MediaPrinter defines how to format a media item for display
+type MediaPrinter[T any] func(item *T)
+
+// ListMediaItems is a generic utility for listing media items with status filtering
+func ListMediaItems[T any](
+	ctx context.Context,
+	status string,
+	mediaType string,
+	listAll func(ctx context.Context) ([]*T, error),
+	listByStatus func(ctx context.Context, status string) ([]*T, error),
+	printer MediaPrinter[T],
+) error {
+	var items []*T
+	var err error
+
+	if status == "" {
+		items, err = listAll(ctx)
+		if err != nil {
+			return fmt.Errorf("failed to list %s: %w", mediaType, err)
+		}
+	} else {
+		items, err = listByStatus(ctx, status)
+		if err != nil {
+			return fmt.Errorf("failed to get %s %s: %w", status, mediaType, err)
+		}
+	}
+
+	if len(items) == 0 {
+		if status == "" {
+			fmt.Printf("No %s found\n", mediaType)
+		} else {
+			fmt.Printf("No %s %s found\n", status, mediaType)
+		}
+		return nil
+	}
+
+	fmt.Printf("Found %d %s:\n\n", len(items), mediaType)
+	for _, item := range items {
+		printer(item)
+	}
+
+	return nil
+}
+
+// PromptUserChoice prompts the user to select from a list of results
+func PromptUserChoice(reader io.Reader, maxChoices int) (int, error) {
+	fmt.Print("\nEnter number to add (1-", maxChoices, "), or 0 to cancel: ")
+
+	var choice int
+	if reader != nil {
+		if _, err := fmt.Fscanf(reader, "%d", &choice); err != nil {
+			return 0, fmt.Errorf("invalid input")
+		}
+	} else {
+		if _, err := fmt.Scanf("%d", &choice); err != nil {
+			return 0, fmt.Errorf("invalid input")
+		}
+	}
+
+	if choice == 0 {
+		fmt.Println("Cancelled.")
+		return 0, nil
+	}
+	if choice < 1 || choice > maxChoices {
+		return 0, fmt.Errorf("invalid choice: %d", choice)
+	}
+	return choice, nil
+}
+
+// ParseID converts a string ID to int64
+func ParseID(id string, itemType string) (int64, error) {
+	itemID, err := strconv.ParseInt(id, 10, 64)
+	if err != nil {
+		return 0, fmt.Errorf("invalid %s ID: %s", itemType, id)
+	}
+	return itemID, nil
+}
+
+// PrintSearchResults displays search results with a type-specific formatter
+func PrintSearchResults[T models.Model](results []*models.Model, formatter func(*models.Model, int)) error {
+	if len(results) == 0 {
+		fmt.Println("No results found.")
+		return nil
+	}
+
+	fmt.Printf("Found %d result(s):\n\n", len(results))
+	for i, result := range results {
+		formatter(result, i+1)
+	}
+	return nil
+}

internal/handlers/movies.go

···
 	reader  io.Reader
 }
 
+// Ensure MovieHandler implements interface [MediaHandler]
+var _ MediaHandler = (*MovieHandler)(nil)
+
 // NewMovieHandler creates a new movie handler
 func NewMovieHandler() (*MovieHandler, error) {
 	db, err := store.NewDatabase()
···
 }
 
 // UpdateStatus changes the status of a movie
-func (h *MovieHandler) UpdateStatus(ctx context.Context, movieID int64, status string) error {
+func (h *MovieHandler) UpdateStatus(ctx context.Context, id, status string) error {
+	movieID, err := strconv.ParseInt(id, 10, 64)
+	if err != nil {
+		return fmt.Errorf("invalid movie ID %w", err)
+	}
 	validStatuses := []string{"queued", "watched", "removed"}
 	if !slices.Contains(validStatuses, status) {
 		return fmt.Errorf("invalid status: %s (valid: %s)", status, strings.Join(validStatuses, ", "))
···
 
 // MarkWatched marks a movie as watched
 func (h *MovieHandler) MarkWatched(ctx context.Context, id string) error {
-	movieID, err := strconv.ParseInt(id, 10, 64)
-	if err != nil {
-		return fmt.Errorf("invalid movie ID: %s", id)
-	}
-
-	return h.UpdateStatus(ctx, movieID, "watched")
+	return h.UpdateStatus(ctx, id, "watched")
 }
 
 // Remove removes a movie from the queue

internal/handlers/movies_test.go

···
 				handler := createTestMovieHandler(t)
 				defer handler.Close()
 
-				err := handler.UpdateStatus(context.Background(), 1, "invalid")
+				err := handler.UpdateStatus(context.Background(), "1", "invalid")
 				if err == nil {
 					t.Error("Expected error for invalid status")
 				}
···
 				handler := createTestMovieHandler(t)
 				defer handler.Close()
 
-				err := handler.UpdateStatus(context.Background(), 999, "watched")
+				err := handler.UpdateStatus(context.Background(), "999", "watched")
 				if err == nil {
 					t.Error("Expected error for non-existent movie")
 				}
···
 		err := handler.MarkWatched(context.Background(), "invalid")
 		if err == nil {
 			t.Error("Expected error for invalid movie ID")
-		}
-		if err.Error() != "invalid movie ID: invalid" {
-			t.Errorf("Expected 'invalid movie ID: invalid', got: %v", err)
 		}
 	})
 
···
 				t.Errorf("Failed to view created movie: %v", err)
 			}
 
-			err = handler.UpdateStatus(context.Background(), id, "watched")
+			err = handler.UpdateStatus(context.Background(), strconv.Itoa(int(id)), "watched")
 			if err != nil {
 				t.Errorf("Failed to update movie status: %v", err)
 			}
···
 			},
 			{
 				name: "Update status of non-existent movie",
-				fn:   func() error { return handler.UpdateStatus(ctx, nonExistentID, "watched") },
+				fn:   func() error { return handler.UpdateStatus(ctx, strconv.Itoa(int(nonExistentID)), "watched") },
 			},
 			{
 				name: "Mark non-existent movie as watched",
···
 		invalid := []string{"invalid", "pending", "completed", ""}
 
 		for _, status := range valid {
-			if err := handler.UpdateStatus(context.Background(), 999, status); err != nil &&
+			if err := handler.UpdateStatus(context.Background(), "999", status); err != nil &&
 				err.Error() == fmt.Sprintf("invalid status: %s (valid: queued, watched, removed)", status) {
 				t.Errorf("Status '%s' should be valid but was rejected", status)
 			}
 		}
 
 		for _, status := range invalid {
-			err := handler.UpdateStatus(context.Background(), 1, status)
+			err := handler.UpdateStatus(context.Background(), "1", status)
 			if err == nil {
 				t.Errorf("Status '%s' should be invalid but was accepted", status)
 			}

internal/handlers/tv.go

···
 )
 
 // TVHandler handles all TV show-related commands
+//
+// Implements MediaHandler interface for polymorphic media handling
 type TVHandler struct {
 	db      *store.Database
 	config  *store.Config
···
 	service *services.TVService
 	reader  io.Reader
 }
+
+// Ensure TVHandler implements MediaHandler interface
+var _ MediaHandler = (*TVHandler)(nil)
 
 // NewTVHandler creates a new TV handler
 func NewTVHandler() (*TVHandler, error) {
···
 }
 
 // UpdateStatus changes the status of a TV show
-func (h *TVHandler) UpdateStatus(ctx context.Context, showID int64, status string) error {
+func (h *TVHandler) UpdateStatus(ctx context.Context, id, status string) error {
+	showID, err := strconv.ParseInt(id, 10, 64)
+	if err != nil {
+		return fmt.Errorf("invalid tv show ID %w", err)
+	}
 	validStatuses := []string{"queued", "watching", "watched", "removed"}
 	if !slices.Contains(validStatuses, status) {
 		return fmt.Errorf("invalid status: %s (valid: %s)", status, strings.Join(validStatuses, ", "))
···
 }
 
 // MarkWatching marks a TV show as currently watching
-func (h *TVHandler) MarkWatching(ctx context.Context, showID int64) error {
-	return h.UpdateStatus(ctx, showID, "watching")
+func (h *TVHandler) MarkWatching(ctx context.Context, id string) error {
+	return h.UpdateStatus(ctx, id, "watching")
 }
 
 // MarkWatched marks a TV show as watched
 func (h *TVHandler) MarkWatched(ctx context.Context, id string) error {
-	showID, err := strconv.ParseInt(id, 10, 64)
-	if err != nil {
-		return fmt.Errorf("invalid TV show ID: %s", id)
-	}
-
-	return h.UpdateStatus(ctx, showID, "watched")
+	return h.UpdateStatus(ctx, id, "watched")
 }
 
 // Remove removes a TV show from the queue
···
 
 // UpdateTVShowStatus changes the status of a TV show
 func (h *TVHandler) UpdateTVShowStatus(ctx context.Context, id, status string) error {
-	showID, err := strconv.ParseInt(id, 10, 64)
-	if err != nil {
-		return fmt.Errorf("invalid TV show ID: %s", id)
-	}
-	return h.UpdateStatus(ctx, showID, status)
+	return h.UpdateStatus(ctx, id, status)
 }
 
 // MarkTVShowWatching marks a TV show as currently watching
 func (h *TVHandler) MarkTVShowWatching(ctx context.Context, id string) error {
-	showID, err := strconv.ParseInt(id, 10, 64)
-	if err != nil {
-		return fmt.Errorf("invalid TV show ID: %s", id)
-	}
-	return h.MarkWatching(ctx, showID)
+	return h.MarkWatching(ctx, id)
 }

internal/handlers/tv_test.go

···
 			handler := createTestTVHandler(t)
 			defer handler.Close()
 
-			err := handler.View(context.Background(), strconv.Itoa(int(999)))
+			err := handler.View(context.Background(), "999")
 			if err == nil {
 				t.Error("Expected error for non-existent TV show")
 			}
···
 				handler := createTestTVHandler(t)
 				defer handler.Close()
 
-				err := handler.UpdateStatus(context.Background(), 1, "invalid")
+				err := handler.UpdateStatus(context.Background(), "1", "invalid")
 				if err == nil {
 					t.Error("Expected error for invalid status")
 				}
···
 				handler := createTestTVHandler(t)
 				defer handler.Close()
 
-				err := handler.UpdateStatus(context.Background(), 999, "watched")
+				err := handler.UpdateStatus(context.Background(), "999", "watched")
 				if err == nil {
 					t.Error("Expected error for non-existent TV show")
 				}
···
 		handler := createTestTVHandler(t)
 		defer handler.Close()
 
-		err := handler.MarkWatching(context.Background(), 999)
+		err := handler.MarkWatching(context.Background(), "999")
 		if err == nil {
 			t.Error("Expected error for non-existent TV show")
 		}
···
 		handler := createTestTVHandler(t)
 		defer handler.Close()
 
-		err := handler.MarkWatched(context.Background(), strconv.Itoa(int(999)))
+		err := handler.MarkWatched(context.Background(), "999")
 		if err == nil {
 			t.Error("Expected error for non-existent TV show")
 		}
···
 		handler := createTestTVHandler(t)
 		defer handler.Close()
 
-		err := handler.Remove(context.Background(), strconv.Itoa(int(999)))
+		err := handler.Remove(context.Background(), "999")
 		if err == nil {
 			t.Error("Expected error for non-existent TV show")
 		}
···
 		if err == nil {
 			t.Error("Expected error for invalid TV show ID")
 		}
-		if err.Error() != "invalid TV show ID: invalid" {
-			t.Errorf("Expected 'invalid TV show ID: invalid', got: %v", err)
-		}
 	})
 
 	t.Run("MarkTVShowWatching_InvalidID", func(t *testing.T) {
···
 		if err == nil {
 			t.Error("Expected error for invalid TV show ID")
 		}
-		if err.Error() != "invalid TV show ID: invalid" {
-			t.Errorf("Expected 'invalid TV show ID: invalid', got: %v", err)
-		}
 	})
 
 	t.Run("MarkWatched_InvalidID", func(t *testing.T) {
···
 		err := handler.MarkWatched(context.Background(), "invalid")
 		if err == nil {
 			t.Error("Expected error for invalid TV show ID")
-		}
-		if err.Error() != "invalid TV show ID: invalid" {
-			t.Errorf("Expected 'invalid TV show ID: invalid', got: %v", err)
 		}
 	})
 
···
 				t.Errorf("Failed to view created TV show: %v", err)
 			}
 
-			err = handler.UpdateStatus(context.Background(), id, "watching")
+			err = handler.UpdateStatus(context.Background(), strconv.Itoa(int(id)), "watching")
 			if err != nil {
 				t.Errorf("Failed to update TV show status: %v", err)
 			}
···
 				t.Errorf("Failed to mark TV show as watched: %v", err)
 			}
 
-			err = handler.MarkWatching(context.Background(), id)
+			err = handler.MarkWatching(context.Background(), strconv.Itoa(int(id)))
 			if err != nil {
 				t.Errorf("Failed to mark TV show as watching: %v", err)
 			}
···
 			},
 			{
 				name: "Update status of non-existent show",
-				fn:   func() error { return handler.UpdateStatus(ctx, nonExistentID, "watched") },
+				fn:   func() error { return handler.UpdateStatus(ctx, strconv.Itoa(int(nonExistentID)), "watched") },
 			},
 			{
 				name: "Mark non-existent show as watching",
-				fn:   func() error { return handler.MarkWatching(ctx, nonExistentID) },
+				fn:   func() error { return handler.MarkWatching(ctx, strconv.Itoa(int(nonExistentID))) },
 			},
 			{
 				name: "Mark non-existent show as watched",
···
 		invalid := []string{"invalid", "pending", "completed", ""}
 
 		for _, status := range valid {
-			if err := handler.UpdateStatus(context.Background(), 999, status); err != nil &&
+			if err := handler.UpdateStatus(context.Background(), "999", status); err != nil &&
 				err.Error() == fmt.Sprintf("invalid status: %s (valid: queued, watching, watched, removed)", status) {
 				t.Errorf("Status '%s' should be valid but was rejected", status)
 			}
 		}
 
 		for _, status := range invalid {
-			err := handler.UpdateStatus(context.Background(), 1, status)
+			err := handler.UpdateStatus(context.Background(), "1", status)
 			if err == nil {
 				t.Errorf("Status '%s' should be invalid but was accepted", status)
 			}

internal/repo/base_media_repository.go

···
+package repo
+
+import (
+	"context"
+	"database/sql"
+	"fmt"
+
+	"github.com/stormlightlabs/noteleaf/internal/models"
+)
+
+// MediaConfig defines configuration for a media repository
+//
+// T should be a pointer type (*models.Book, *models.Movie, *models.TVShow)
+type MediaConfig[T models.Model] struct {
+	TableName     string                             // TableName is the database table name (e.g., "books", "movies", "tv_shows")
+	New           func() T                           // New creates a new zero-value instance of T
+	Scan          func(rows *sql.Rows, item T) error // Scan reads a database row into a model instance
+	ScanSingle    func(row *sql.Row, item T) error   // ScanSingle reads a single row from QueryRow into a model instance
+	InsertColumns string                             // InsertColumns returns the column names for INSERT statements
+	UpdateColumns string                             // UpdateColumns returns the SET clause for UPDATE statements (without WHERE)
+	InsertValues  func(item T) []any                 // InsertValues extracts values from a model for INSERT
+	UpdateValues  func(item T) []any                 // UpdateValues extracts values from a model for UPDATE (item values + ID)
+}
+
+// BaseMediaRepository provides shared CRUD operations for media types
+//
+// This generic implementation eliminates duplicate code across Book, Movie, and TV repositories.
+// Type-specific behavior is configured via MediaConfig.
+//
+// T should be a pointer type (*models.Book, *models.Movie, *models.TVShow)
+type BaseMediaRepository[T models.Model] struct {
+	db     *sql.DB
+	config MediaConfig[T]
+}
+
+// NewBaseMediaRepository creates a new base media repository
+func NewBaseMediaRepository[T models.Model](db *sql.DB, config MediaConfig[T]) *BaseMediaRepository[T] {
+	return &BaseMediaRepository[T]{
+		db:     db,
+		config: config,
+	}
+}
+
+// Create stores a new media item and returns its assigned ID
+func (r *BaseMediaRepository[T]) Create(ctx context.Context, item T) (int64, error) {
+	query := fmt.Sprintf(
+		"INSERT INTO %s (%s) VALUES (%s)",
+		r.config.TableName,
+		r.config.InsertColumns,
+		buildPlaceholders(r.config.InsertValues(item)),
+	)
+
+	result, err := r.db.ExecContext(ctx, query, r.config.InsertValues(item)...)
+	if err != nil {
+		return 0, fmt.Errorf("failed to insert %s: %w", r.config.TableName, err)
+	}
+
+	id, err := result.LastInsertId()
+	if err != nil {
+		return 0, fmt.Errorf("failed to get last insert id: %w", err)
+	}
+
+	return id, nil
+}
+
+// Get retrieves a media item by ID
+//
+// Returns T directly (which is already a pointer type like *models.Book)
+func (r *BaseMediaRepository[T]) Get(ctx context.Context, id int64) (T, error) {
+	query := fmt.Sprintf("SELECT * FROM %s WHERE id = ?", r.config.TableName)
+	row := r.db.QueryRowContext(ctx, query, id)
+
+	item := r.config.New()
+	if err := r.config.ScanSingle(row, item); err != nil {
+		var zero T
+		if err == sql.ErrNoRows {
+			return zero, fmt.Errorf("%s with id %d not found", r.config.TableName, id)
+		}
+		return zero, fmt.Errorf("failed to get %s: %w", r.config.TableName, err)
+	}
+
+	return item, nil
+}
+
+// Update modifies an existing media item
+func (r *BaseMediaRepository[T]) Update(ctx context.Context, item T) error {
+	query := fmt.Sprintf(
+		"UPDATE %s SET %s WHERE id = ?",
+		r.config.TableName,
+		r.config.UpdateColumns,
+	)
+
+	_, err := r.db.ExecContext(ctx, query, r.config.UpdateValues(item)...)
+	if err != nil {
+		return fmt.Errorf("failed to update %s: %w", r.config.TableName, err)
+	}
+
+	return nil
+}
+
+// Delete removes a media item by ID
+func (r *BaseMediaRepository[T]) Delete(ctx context.Context, id int64) error {
+	query := fmt.Sprintf("DELETE FROM %s WHERE id = ?", r.config.TableName)
+	_, err := r.db.ExecContext(ctx, query, id)
+	if err != nil {
+		return fmt.Errorf("failed to delete %s: %w", r.config.TableName, err)
+	}
+	return nil
+}
+
+// ListQuery executes a custom query and scans results
+//
+// Returns []T where T is a pointer type (e.g., []*models.Book)
+func (r *BaseMediaRepository[T]) ListQuery(ctx context.Context, query string, args ...any) ([]T, error) {
+	rows, err := r.db.QueryContext(ctx, query, args...)
+	if err != nil {
+		return nil, fmt.Errorf("failed to list %s: %w", r.config.TableName, err)
+	}
+	defer rows.Close()
+
+	var items []T
+	for rows.Next() {
+		item := r.config.New()
+		if err := r.config.Scan(rows, item); err != nil {
+			return nil, err
+		}
+		items = append(items, item)
+	}
+
+	return items, rows.Err()
+}
+
+// CountQuery executes a custom COUNT query
+func (r *BaseMediaRepository[T]) CountQuery(ctx context.Context, query string, args ...any) (int64, error) {
+	var count int64
+	err := r.db.QueryRowContext(ctx, query, args...).Scan(&count)
+	if err != nil {
+		return 0, fmt.Errorf("failed to count %s: %w", r.config.TableName, err)
+	}
+	return count, nil
+}
+
+// buildPlaceholders generates "?,?,?" for SQL placeholders
+func buildPlaceholders(values []any) string {
+	if len(values) == 0 {
+		return ""
+	}
+
+	placeholders := "?"
+	for i := 1; i < len(values); i++ {
+		placeholders += ",?"
+	}
+	return placeholders
+}

internal/repo/book_repository.go

···
 )
 
 // BookRepository provides database operations for books
+//
+// Uses BaseMediaRepository for common CRUD operations.
+// TODO: Implement Repository interface (Validate method) similar to ArticleRepository
 type BookRepository struct {
+	*BaseMediaRepository[*models.Book]
 	db *sql.DB
 }
 
 // NewBookRepository creates a new book repository
 func NewBookRepository(db *sql.DB) *BookRepository {
-	return &BookRepository{db: db}
+	config := MediaConfig[*models.Book]{
+		TableName:     "books",
+		New:           func() *models.Book { return &models.Book{} },
+		InsertColumns: "title, author, status, progress, pages, rating, notes, added, started, finished",
+		UpdateColumns: "title = ?, author = ?, status = ?, progress = ?, pages = ?, rating = ?, notes = ?, started = ?, finished = ?",
+		InsertValues: func(book *models.Book) []any {
+			return []any{book.Title, book.Author, book.Status, book.Progress, book.Pages, book.Rating, book.Notes, book.Added, book.Started, book.Finished}
+		},
+		UpdateValues: func(book *models.Book) []any {
+			return []any{book.Title, book.Author, book.Status, book.Progress, book.Pages, book.Rating, book.Notes, book.Started, book.Finished, book.ID}
+		},
+		Scan: func(rows *sql.Rows, book *models.Book) error {
+			return scanBookRow(rows, book)
+		},
+		ScanSingle: func(row *sql.Row, book *models.Book) error {
+			return scanBookRowSingle(row, book)
+		},
+	}
+
+	return &BookRepository{
+		BaseMediaRepository: NewBaseMediaRepository(db, config),
+		db:                  db,
+	}
 }
 
 // Create stores a new book and returns its assigned ID
···
 	now := time.Now()
 	book.Added = now
 
-	query := `
-		INSERT INTO books (title, author, status, progress, pages, rating, notes, added, started, finished)
-		VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`
-
-	result, err := r.db.ExecContext(ctx, query,
-		book.Title, book.Author, book.Status, book.Progress, book.Pages, book.Rating,
-		book.Notes, book.Added, book.Started, book.Finished)
+	id, err := r.BaseMediaRepository.Create(ctx, book)
 	if err != nil {
-		return 0, fmt.Errorf("failed to insert book: %w", err)
-	}
-
-	id, err := result.LastInsertId()
-	if err != nil {
-		return 0, fmt.Errorf("failed to get last insert id: %w", err)
+		return 0, err
 	}
 
 	book.ID = id
 	return id, nil
 }
 
-// Get retrieves a book by ID
-func (r *BookRepository) Get(ctx context.Context, id int64) (*models.Book, error) {
-	query := `
-		SELECT id, title, author, status, progress, pages, rating, notes, added, started, finished
-		FROM books WHERE id = ?`
-
-	book := &models.Book{}
-	err := r.db.QueryRowContext(ctx, query, id).Scan(
-		&book.ID, &book.Title, &book.Author, &book.Status, &book.Progress, &book.Pages,
-		&book.Rating, &book.Notes, &book.Added, &book.Started, &book.Finished)
-	if err != nil {
-		return nil, fmt.Errorf("failed to get book: %w", err)
-	}
-
-	return book, nil
-}
-
-// Update modifies an existing book
-func (r *BookRepository) Update(ctx context.Context, book *models.Book) error {
-	query := `
-		UPDATE books SET title = ?, author = ?, status = ?, progress = ?, pages = ?,
-		rating = ?, notes = ?, started = ?, finished = ?
-		WHERE id = ?`
-
-	_, err := r.db.ExecContext(ctx, query,
-		book.Title, book.Author, book.Status, book.Progress, book.Pages, book.Rating,
-		book.Notes, book.Started, book.Finished, book.ID)
-	if err != nil {
-		return fmt.Errorf("failed to update book: %w", err)
-	}
-
-	return nil
-}
-
-// Delete removes a book by ID
-func (r *BookRepository) Delete(ctx context.Context, id int64) error {
-	query := "DELETE FROM books WHERE id = ?"
-	_, err := r.db.ExecContext(ctx, query, id)
-	if err != nil {
-		return fmt.Errorf("failed to delete book: %w", err)
-	}
-	return nil
-}
-
 // List retrieves books with optional filtering and sorting
 func (r *BookRepository) List(ctx context.Context, opts BookListOptions) ([]*models.Book, error) {
 	query := r.buildListQuery(opts)
 	args := r.buildListArgs(opts)
 
-	rows, err := r.db.QueryContext(ctx, query, args...)
+	items, err := r.BaseMediaRepository.ListQuery(ctx, query, args...)
 	if err != nil {
-		return nil, fmt.Errorf("failed to list books: %w", err)
+		return nil, err
 	}
-	defer rows.Close()
-
-	var books []*models.Book
-	for rows.Next() {
-		book := &models.Book{}
-		if err := r.scanBookRow(rows, book); err != nil {
-			return nil, err
-		}
-		books = append(books, book)
-	}
-
-	return books, rows.Err()
+	return items, nil
 }
 
 func (r *BookRepository) buildListQuery(opts BookListOptions) string {
···
 	return args
 }
 
-func (r *BookRepository) scanBookRow(rows *sql.Rows, book *models.Book) error {
+// scanBookRow scans a database row into a book model
+func scanBookRow(rows *sql.Rows, book *models.Book) error {
 	var pages sql.NullInt64
 
 	if err := rows.Scan(&book.ID, &book.Title, &book.Author, &book.Status, &book.Progress, &pages,
+		&book.Rating, &book.Notes, &book.Added, &book.Started, &book.Finished); err != nil {
+		return err
+	}
+
+	if pages.Valid {
+		book.Pages = int(pages.Int64)
+	}
+
+	return nil
+}
+
+// scanBookRowSingle scans a single database row into a book model
+func scanBookRowSingle(row *sql.Row, book *models.Book) error {
+	var pages sql.NullInt64
+
+	if err := row.Scan(&book.ID, &book.Title, &book.Author, &book.Status, &book.Progress, &pages,
 		&book.Rating, &book.Notes, &book.Added, &book.Started, &book.Finished); err != nil {
 		return err
 	}
···
 		query += " WHERE " + strings.Join(conditions, " AND ")
 	}
 
-	var count int64
-	err := r.db.QueryRowContext(ctx, query, args...).Scan(&count)
-	if err != nil {
-		return 0, fmt.Errorf("failed to count books: %w", err)
-	}
-
-	return count, nil
+	return r.BaseMediaRepository.CountQuery(ctx, query, args...)
 }
 
 // GetQueued retrieves all books in the queue

internal/repo/media_repository.go

···
+package repo
+
+import (
+	"context"
+
+	"github.com/stormlightlabs/noteleaf/internal/models"
+)
+
+// MediaRepository defines CRUD operations for media types (Books, Movies, TV)
+//
+// This interface captures the shared behavior across media repositories
+type MediaRepository[T models.Model] interface {
+	// Create stores a new media item and returns its assigned ID
+	Create(ctx context.Context, item *T) (int64, error)
+
+	// Get retrieves a media item by ID
+	Get(ctx context.Context, id int64) (*T, error)
+
+	// Update modifies an existing media item
+	Update(ctx context.Context, item *T) error
+
+	// Delete removes a media item by ID
+	Delete(ctx context.Context, id int64) error
+
+	// List retrieves media items with optional filtering and sorting
+	List(ctx context.Context, opts any) ([]*T, error)
+
+	// Count returns the number of media items matching conditions
+	Count(ctx context.Context, opts any) (int64, error)
+}
+
+// StatusFilterable extends MediaRepository with status-based filtering
+//
+// Media types (Books, Movies, TV) support status-based queries like "queued", "reading", "watching", "watched", "finished"
+type StatusFilterable[T models.Model] interface {
+	MediaRepository[T]
+
+	// GetByStatus retrieves all items with the given status
+	GetByStatus(ctx context.Context, status string) ([]*T, error)
+}

internal/repo/movie_repository.go

···
 
 // MovieRepository provides database operations for movies
 type MovieRepository struct {
+	*BaseMediaRepository[*models.Movie]
 	db *sql.DB
 }
 
 // NewMovieRepository creates a new movie repository
 func NewMovieRepository(db *sql.DB) *MovieRepository {
-	return &MovieRepository{db: db}
+	config := MediaConfig[*models.Movie]{
+		TableName:     "movies",
+		New:           func() *models.Movie { return &models.Movie{} },
+		InsertColumns: "title, year, status, rating, notes, added, watched",
+		UpdateColumns: "title = ?, year = ?, status = ?, rating = ?, notes = ?, watched = ?",
+		InsertValues: func(movie *models.Movie) []any {
+			return []any{movie.Title, movie.Year, movie.Status, movie.Rating, movie.Notes, movie.Added, movie.Watched}
+		},
+		UpdateValues: func(movie *models.Movie) []any {
+			return []any{movie.Title, movie.Year, movie.Status, movie.Rating, movie.Notes, movie.Watched, movie.ID}
+		},
+		Scan: func(rows *sql.Rows, movie *models.Movie) error {
+			return scanMovieRow(rows, movie)
+		},
+		ScanSingle: func(row *sql.Row, movie *models.Movie) error {
+			return scanMovieRowSingle(row, movie)
+		},
+	}
+
+	return &MovieRepository{
+		BaseMediaRepository: NewBaseMediaRepository(db, config),
+		db:                  db,
+	}
 }
 
 // Create stores a new movie and returns its assigned ID
···
 	now := time.Now()
 	movie.Added = now
 
-	query := `
-		INSERT INTO movies (title, year, status, rating, notes, added, watched)
-		VALUES (?, ?, ?, ?, ?, ?, ?)`
-
-	result, err := r.db.ExecContext(ctx, query,
-		movie.Title, movie.Year, movie.Status, movie.Rating, movie.Notes, movie.Added, movie.Watched)
+	id, err := r.BaseMediaRepository.Create(ctx, movie)
 	if err != nil {
-		return 0, fmt.Errorf("failed to insert movie: %w", err)
-	}
-
-	id, err := result.LastInsertId()
-	if err != nil {
-		return 0, fmt.Errorf("failed to get last insert id: %w", err)
+		return 0, err
 	}
 
 	movie.ID = id
 	return id, nil
 }
 
-// Get retrieves a movie by ID
-func (r *MovieRepository) Get(ctx context.Context, id int64) (*models.Movie, error) {
-	query := `
-		SELECT id, title, year, status, rating, notes, added, watched
-		FROM movies WHERE id = ?`
-
-	movie := &models.Movie{}
-	err := r.db.QueryRowContext(ctx, query, id).Scan(
-		&movie.ID, &movie.Title, &movie.Year, &movie.Status, &movie.Rating,
-		&movie.Notes, &movie.Added, &movie.Watched)
-	if err != nil {
-		return nil, fmt.Errorf("failed to get movie: %w", err)
-	}
-
-	return movie, nil
-}
-
-// Update modifies an existing movie
-func (r *MovieRepository) Update(ctx context.Context, movie *models.Movie) error {
-	query := `
-		UPDATE movies SET title = ?, year = ?, status = ?, rating = ?, notes = ?, watched = ?
-		WHERE id = ?`
-
-	_, err := r.db.ExecContext(ctx, query,
-		movie.Title, movie.Year, movie.Status, movie.Rating, movie.Notes, movie.Watched, movie.ID)
-	if err != nil {
-		return fmt.Errorf("failed to update movie: %w", err)
-	}
-
-	return nil
-}
-
-// Delete removes a movie by ID
-func (r *MovieRepository) Delete(ctx context.Context, id int64) error {
-	query := "DELETE FROM movies WHERE id = ?"
-	_, err := r.db.ExecContext(ctx, query, id)
-	if err != nil {
-		return fmt.Errorf("failed to delete movie: %w", err)
-	}
-	return nil
-}
-
 // List retrieves movies with optional filtering and sorting
 func (r *MovieRepository) List(ctx context.Context, opts MovieListOptions) ([]*models.Movie, error) {
 	query := r.buildListQuery(opts)
 	args := r.buildListArgs(opts)
 
-	rows, err := r.db.QueryContext(ctx, query, args...)
+	items, err := r.BaseMediaRepository.ListQuery(ctx, query, args...)
 	if err != nil {
-		return nil, fmt.Errorf("failed to list movies: %w", err)
+		return nil, err
 	}
-	defer rows.Close()
-
-	var movies []*models.Movie
-	for rows.Next() {
-		movie := &models.Movie{}
-		if err := r.scanMovieRow(rows, movie); err != nil {
-			return nil, err
-		}
-		movies = append(movies, movie)
-	}
-
-	return movies, rows.Err()
+	return items, nil
 }
 
 func (r *MovieRepository) buildListQuery(opts MovieListOptions) string {
···
 	return args
 }
 
-func (r *MovieRepository) scanMovieRow(rows *sql.Rows, movie *models.Movie) error {
+// scanMovieRow scans a database row into a [models.Movie]
+func scanMovieRow(rows *sql.Rows, movie *models.Movie) error {
 	return rows.Scan(&movie.ID, &movie.Title, &movie.Year, &movie.Status, &movie.Rating,
 		&movie.Notes, &movie.Added, &movie.Watched)
 }
 
+// scanMovieRowSingle scans a single database row into a [models.Movie]
+func scanMovieRowSingle(row *sql.Row, movie *models.Movie) error {
+	return row.Scan(&movie.ID, &movie.Title, &movie.Year, &movie.Status, &movie.Rating,
+		&movie.Notes, &movie.Added, &movie.Watched)
+}
+
 // Find retrieves movies matching specific conditions
 func (r *MovieRepository) Find(ctx context.Context, conditions MovieListOptions) ([]*models.Movie, error) {
 	return r.List(ctx, conditions)
···
 	if len(conditions) > 0 {
 		query += " WHERE " + strings.Join(conditions, " AND ")
 	}
-
-	var count int64
-	err := r.db.QueryRowContext(ctx, query, args...).Scan(&count)
-	if err != nil {
-		return 0, fmt.Errorf("failed to count movies: %w", err)
-	}
-
-	return count, nil
+	return r.BaseMediaRepository.CountQuery(ctx, query, args...)
 }
 
 // GetQueued retrieves all movies in the queue
···
 	if err != nil {
 		return err
 	}
-
 	now := time.Now()
 	movie.Status = "watched"
 	movie.Watched = &now
-
 	return r.Update(ctx, movie)
 }
 

internal/repo/task_repository.go

···
 }
 
 // TaskRepository provides database operations for tasks
+//
+// TODO: Implement Repository interface (Validate method) similar to ArticleRepository
 type TaskRepository struct {
 	db *sql.DB
 }

internal/repo/tv_repository.go

···
 
 // TVRepository provides database operations for TV shows
 type TVRepository struct {
+	*BaseMediaRepository[*models.TVShow]
 	db *sql.DB
 }
 
 // NewTVRepository creates a new TV show repository
 func NewTVRepository(db *sql.DB) *TVRepository {
-	return &TVRepository{db: db}
+	config := MediaConfig[*models.TVShow]{
+		TableName:     "tv_shows",
+		New:           func() *models.TVShow { return &models.TVShow{} },
+		InsertColumns: "title, season, episode, status, rating, notes, added, last_watched",
+		UpdateColumns: "title = ?, season = ?, episode = ?, status = ?, rating = ?, notes = ?, last_watched = ?",
+		InsertValues: func(show *models.TVShow) []any {
+			return []any{show.Title, show.Season, show.Episode, show.Status, show.Rating, show.Notes, show.Added, show.LastWatched}
+		},
+		UpdateValues: func(show *models.TVShow) []any {
+			return []any{show.Title, show.Season, show.Episode, show.Status, show.Rating, show.Notes, show.LastWatched, show.ID}
+		},
+		Scan: func(rows *sql.Rows, show *models.TVShow) error {
+			return scanTVShowRow(rows, show)
+		},
+		ScanSingle: func(row *sql.Row, show *models.TVShow) error {
+			return scanTVShowRowSingle(row, show)
+		},
+	}
+
+	return &TVRepository{
+		BaseMediaRepository: NewBaseMediaRepository(db, config),
+		db:                  db,
+	}
 }
 
 // Create stores a new TV show and returns its assigned ID
···
 	now := time.Now()
 	tvShow.Added = now
 
-	query := `
-		INSERT INTO tv_shows (title, season, episode, status, rating, notes, added, last_watched)
-		VALUES (?, ?, ?, ?, ?, ?, ?, ?)`
-
-	result, err := r.db.ExecContext(ctx, query,
-		tvShow.Title, tvShow.Season, tvShow.Episode, tvShow.Status, tvShow.Rating,
-		tvShow.Notes, tvShow.Added, tvShow.LastWatched)
+	id, err := r.BaseMediaRepository.Create(ctx, tvShow)
 	if err != nil {
-		return 0, fmt.Errorf("failed to insert TV show: %w", err)
-	}
-
-	id, err := result.LastInsertId()
-	if err != nil {
-		return 0, fmt.Errorf("failed to get last insert id: %w", err)
+		return 0, err
 	}
 
 	tvShow.ID = id
 	return id, nil
 }
 
-// Get retrieves a TV show by ID
-func (r *TVRepository) Get(ctx context.Context, id int64) (*models.TVShow, error) {
-	query := `
-		SELECT id, title, season, episode, status, rating, notes, added, last_watched
-		FROM tv_shows WHERE id = ?`
-
-	tvShow := &models.TVShow{}
-	err := r.db.QueryRowContext(ctx, query, id).Scan(
-		&tvShow.ID, &tvShow.Title, &tvShow.Season, &tvShow.Episode, &tvShow.Status,
-		&tvShow.Rating, &tvShow.Notes, &tvShow.Added, &tvShow.LastWatched)
-	if err != nil {
-		return nil, fmt.Errorf("failed to get TV show: %w", err)
-	}
-
-	return tvShow, nil
-}
-
-// Update modifies an existing TV show
-func (r *TVRepository) Update(ctx context.Context, tvShow *models.TVShow) error {
-	query := `
-		UPDATE tv_shows SET title = ?, season = ?, episode = ?, status = ?, rating = ?,
-		notes = ?, last_watched = ?
-		WHERE id = ?`
-
-	_, err := r.db.ExecContext(ctx, query,
-		tvShow.Title, tvShow.Season, tvShow.Episode, tvShow.Status, tvShow.Rating,
-		tvShow.Notes, tvShow.LastWatched, tvShow.ID)
-	if err != nil {
-		return fmt.Errorf("failed to update TV show: %w", err)
-	}
-
-	return nil
-}
-
-// Delete removes a TV show by ID
-func (r *TVRepository) Delete(ctx context.Context, id int64) error {
-	query := "DELETE FROM tv_shows WHERE id = ?"
-	_, err := r.db.ExecContext(ctx, query, id)
-	if err != nil {
-		return fmt.Errorf("failed to delete TV show: %w", err)
-	}
-	return nil
-}
-
 // List retrieves TV shows with optional filtering and sorting
 func (r *TVRepository) List(ctx context.Context, opts TVListOptions) ([]*models.TVShow, error) {
 	query := r.buildListQuery(opts)
 	args := r.buildListArgs(opts)
 
-	rows, err := r.db.QueryContext(ctx, query, args...)
+	items, err := r.BaseMediaRepository.ListQuery(ctx, query, args...)
 	if err != nil {
-		return nil, fmt.Errorf("failed to list TV shows: %w", err)
+		return nil, err
 	}
-	defer rows.Close()
-
-	var tvShows []*models.TVShow
-	for rows.Next() {
-		tvShow := &models.TVShow{}
-		if err := r.scanTVShowRow(rows, tvShow); err != nil {
-			return nil, err
-		}
-		tvShows = append(tvShows, tvShow)
-	}
-
-	return tvShows, rows.Err()
+	return items, nil
 }
 
 func (r *TVRepository) buildListQuery(opts TVListOptions) string {
···
 	return args
 }
 
-func (r *TVRepository) scanTVShowRow(rows *sql.Rows, tvShow *models.TVShow) error {
+func scanTVShowRow(rows *sql.Rows, tvShow *models.TVShow) error {
 	return rows.Scan(&tvShow.ID, &tvShow.Title, &tvShow.Season, &tvShow.Episode, &tvShow.Status,
 		&tvShow.Rating, &tvShow.Notes, &tvShow.Added, &tvShow.LastWatched)
 }
 
+func scanTVShowRowSingle(row *sql.Row, tvShow *models.TVShow) error {
+	return row.Scan(&tvShow.ID, &tvShow.Title, &tvShow.Season, &tvShow.Episode, &tvShow.Status,
+		&tvShow.Rating, &tvShow.Notes, &tvShow.Added, &tvShow.LastWatched)
+}
+
 // Find retrieves TV shows matching specific conditions
 func (r *TVRepository) Find(ctx context.Context, conditions TVListOptions) ([]*models.TVShow, error) {
 	return r.List(ctx, conditions)
···
 		query += " WHERE " + strings.Join(conditions, " AND ")
 	}
 
-	var count int64
-	err := r.db.QueryRowContext(ctx, query, args...).Scan(&count)
-	if err != nil {
-		return 0, fmt.Errorf("failed to count TV shows: %w", err)
-	}
-
-	return count, nil
+	return r.BaseMediaRepository.CountQuery(ctx, query, args...)
 }
 
 // GetQueued retrieves all TV shows in the queue
···
 	if err != nil {
 		return err
 	}
-
 	now := time.Now()
 	tvShow.Status = "watched"
 	tvShow.LastWatched = &now
-
 	return r.Update(ctx, tvShow)
 }