First rough implementation of scrobble rules (Claude)

This plan outlines the implementation of functionality to manage
arbitrary rules for fixing data in the `scrobbled_tracks` table. The
system will support two types of transformations:

1. **Album Rule**: Update the album MusicBrainz ID of all tracks
belonging to a specific album (identified by album title)
2. **Artist Rule**: Update the artist MusicBrainz ID of all tracks
belonging to a specific artist (identified by artist name)

- `scrobbled_tracks` table exists with the following structure:
  - `scrobbled_at_uts` (integer, primary key)
  - `musicbrainz_id` (string) - track MusicBrainz ID
  - `title` (string) - track title
  - `cover_url` (string)
  - `scrobbled_at_label` (string)
  - `artist` (map) - embedded artist data with `musicbrainz_id` and
`name`
  - `album` (map) - embedded album data with `musicbrainz_id` and
`title`
  - `last_fm_data` (map) - raw Last.fm API response

- `LastFm.Track` - Schema for scrobbled tracks
- `LastFm.Artist` - Embedded artist schema
- `LastFm.Album` - Embedded album schema

- Main navigation has Stats, Collection, Wishlist sections
- "More" dropdown contains development tools and utilities
- Uses Phoenix LiveView for interactive components

**File**:
`priv/repo/migrations/YYYYMMDDHHMMSS_create_scrobble_rules.exs`

Create `scrobble_rules` table with:

- `id` (primary key)
- `type` (string) - "album" or "artist"
- `match_value` (string) - album title or artist name to match
- `target_musicbrainz_id` (string) - MusicBrainz ID to set
- `enabled` (boolean) - whether rule is active
- `description` (text) - optional description for the rule
- `inserted_at` (timestamp)
- `updated_at` (timestamp)

Indexes:

- `type, match_value` (compound index for efficient matching)
- `enabled` (for filtering active rules)

**File**: `lib/music_library/scrobble_rules/scrobble_rule.ex`

Create Ecto schema with:

- Field definitions matching migration
- Validations:
  - `type` must be "album" or "artist"
  - `match_value` required and non-empty
  - `target_musicbrainz_id` required and non-empty
  - `enabled` defaults to true
- Changeset functions for create/update operations

**File**: `lib/music_library/scrobble_rules.ex`

Implement context functions:

- `list_scrobble_rules(opts \\ [])` - list all rules with optional
filtering
- `get_scrobble_rule!(id)` - get specific rule by ID
- `create_scrobble_rule(attrs)` - create new rule
- `update_scrobble_rule(rule, attrs)` - update existing rule
- `delete_scrobble_rule(rule)` - delete rule
- `change_scrobble_rule(rule, attrs \\ %{})` - create changeset
- `list_enabled_rules()` - get only enabled rules for worker
- `apply_album_rule(rule)` - apply album transformation
- `apply_artist_rule(rule)` - apply artist transformation
- `apply_all_rules()` - apply all enabled rules

**File**: `lib/music_library_web/components/layouts/app.html.heex`

Add new navigation link in the "More" dropdown:

- Icon: `hero-adjustments-horizontal`
- Label: "Scrobble Rules"
- Route: `/scrobble-rules`
- Position: After "Oban" link, before separator

**File**: `lib/music_library_web/router.ex`

Add new LiveView routes in the authenticated scope:

- `/scrobble-rules` - index page
- `/scrobble-rules/new` - create new rule
- `/scrobble-rules/:id/edit` - edit existing rule

**File**: `lib/music_library_web/live/scrobble_rules_live/index.ex`

Implement LiveView with:

- List view showing all rules with status indicators
- Create/Edit forms with validation
- Delete confirmation
- Filter controls (by type, enabled/disabled)
- Manual rule application triggers
- Real-time updates via PubSub

**Template**:
`lib/music_library_web/live/scrobble_rules_live/index.html.heex`

- Table layout with rule details
- Action buttons (Edit, Delete, Apply)
- Form components for create/edit
- Status indicators for enabled/disabled rules

**File**:
`lib/music_library_web/live/scrobble_rules_live/form_component.ex`

Create reusable form component:

- Type selection (album/artist)
- Match value input with validation
- Target MusicBrainz ID input
- Description textarea
- Enable/disable toggle
- Save/Cancel actions

Where possible, use the components available at
<https://docs.fluxonui.com/1.1.4/overview.html>.

**File**: `lib/music_library/scrobble_rules/worker.ex`

Implement Oban worker:

- Scheduled to run periodically (e.g., every 30 minutes)
- Fetches all enabled rules
- Applies each rule in sequence
- Logs application results
- Handles errors gracefully
- Tracks last application time

**File**: `test/music_library/scrobble_rules_test.exs`

- Test all context functions
- Test rule application logic
- Test edge cases and error handling

**File**: `test/music_library/scrobble_rules/scrobble_rule_test.exs`

- Test schema validations
- Test changeset functions
- Test constraint validations

**File**: `test/music_library_web/live/scrobble_rules_live_test.exs`

- Test LiveView interactions
- Test form submissions
- Test real-time updates
- Test navigation and routing

**File**: `test/music_library/scrobble_rules/worker_test.exs`

- Test job execution
- Test rule application
- Test error handling
- Test scheduling

- Ensure atomic operations when applying rules
- Validate MusicBrainz IDs before applying
- Log all transformations for audit trail

- Index optimization for rule matching
- Batch processing for large datasets
- Rate limiting for external API calls

- Clear feedback on rule application
- Preview mode to show what would change
- Bulk operations for managing multiple rules
- Export/import functionality for rule sets

- Input validation and sanitization
- Rate limiting on rule creation
- Audit logging for all changes

```sql
-- scrobble_rules table
CREATE TABLE scrobble_rules (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  type TEXT NOT NULL CHECK (type IN ('album', 'artist')),
  match_value TEXT NOT NULL,
  target_musicbrainz_id TEXT NOT NULL,
  enabled BOOLEAN NOT NULL DEFAULT TRUE,
  description TEXT,
  inserted_at TIMESTAMP NOT NULL,
  updated_at TIMESTAMP NOT NULL
);

CREATE INDEX idx_scrobble_rules_type_match ON scrobble_rules(type,
match_value);
CREATE INDEX idx_scrobble_rules_enabled ON scrobble_rules(enabled);
```

```
lib/music_library/
├── scrobble_rules/
│   ├── scrobble_rule.ex          # Schema
│   └── worker.ex                 # Oban worker
└── scrobble_rules.ex             # Context

lib/music_library_web/
└── live/
    └── scrobble_rules_live/
        ├── index.ex              # LiveView
        ├── index.html.heex       # Template
        └── form_component.ex     # Form component

priv/repo/migrations/
└── YYYYMMDDHHMMSS_create_scrobble_rules.exs

test/
├── music_library/
│   ├── scrobble_rules_test.exs
│   └── scrobble_rules/
│       ├── scrobble_rule_test.exs
│       └── worker_test.exs
└── music_library_web/
    └── live/
        └── scrobble_rules_live_test.exs
```

1. Database migration and schema
2. Context module with basic CRUD operations
3. LiveView interface for rule management
4. Navigation and routing updates
5. Periodic worker implementation
6. Comprehensive testing
7. Documentation and deployment

This plan ensures a robust, maintainable solution that integrates
seamlessly with the existing Music Library application architecture.

lib/music_library/scrobble_rules.ex

@@ -0,0 +1,324 @@
+defmodule MusicLibrary.ScrobbleRules do
+  @moduledoc """
+  The ScrobbleRules context.
+  """
+
+  import Ecto.Query, warn: false
+
+  alias LastFm.Track
+  alias MusicLibrary.Repo
+  alias MusicLibrary.ScrobbleRules.ScrobbleRule
+
+  @doc """
+  Returns the list of scrobble_rules.
+
+  ## Examples
+
+      iex> list_scrobble_rules()
+      [%ScrobbleRule{}, ...]
+
+  """
+  def list_scrobble_rules(opts \\ []) do
+    query = from(r in ScrobbleRule, order_by: [desc: r.inserted_at])
+
+    query =
+      case Keyword.get(opts, :type) do
+        nil -> query
+        type -> from(r in query, where: r.type == ^type)
+      end
+
+    query =
+      case Keyword.get(opts, :enabled) do
+        nil -> query
+        enabled -> from(r in query, where: r.enabled == ^enabled)
+      end
+
+    Repo.all(query)
+  end
+
+  @doc """
+  Gets a single scrobble_rule.
+
+  Raises `Ecto.NoResultsError` if the Scrobble rule does not exist.
+
+  ## Examples
+
+      iex> get_scrobble_rule!(123)
+      %ScrobbleRule{}
+
+      iex> get_scrobble_rule!(456)
+      ** (Ecto.NoResultsError)
+
+  """
+  def get_scrobble_rule!(id), do: Repo.get!(ScrobbleRule, id)
+
+  @doc """
+  Creates a scrobble_rule.
+
+  ## Examples
+
+      iex> create_scrobble_rule(%{field: value})
+      {:ok, %ScrobbleRule{}}
+
+      iex> create_scrobble_rule(%{field: bad_value})
+      {:error, %Ecto.Changeset{}}
+
+  """
+  def create_scrobble_rule(attrs \\ %{}) do
+    %ScrobbleRule{}
+    |> ScrobbleRule.changeset(attrs)
+    |> Repo.insert()
+  end
+
+  @doc """
+  Updates a scrobble_rule.
+
+  ## Examples
+
+      iex> update_scrobble_rule(scrobble_rule, %{field: new_value})
+      {:ok, %ScrobbleRule{}}
+
+      iex> update_scrobble_rule(scrobble_rule, %{field: bad_value})
+      {:error, %Ecto.Changeset{}}
+
+  """
+  def update_scrobble_rule(%ScrobbleRule{} = scrobble_rule, attrs) do
+    scrobble_rule
+    |> ScrobbleRule.changeset(attrs)
+    |> Repo.update()
+  end
+
+  @doc """
+  Deletes a scrobble_rule.
+
+  ## Examples
+
+      iex> delete_scrobble_rule(scrobble_rule)
+      {:ok, %ScrobbleRule{}}
+
+      iex> delete_scrobble_rule(scrobble_rule)
+      {:error, %Ecto.Changeset{}}
+
+  """
+  def delete_scrobble_rule(%ScrobbleRule{} = scrobble_rule) do
+    Repo.delete(scrobble_rule)
+  end
+
+  @doc """
+  Returns an `%Ecto.Changeset{}` for tracking scrobble_rule changes.
+
+  ## Examples
+
+      iex> change_scrobble_rule(scrobble_rule)
+      %Ecto.Changeset{data: %ScrobbleRule{}}
+
+  """
+  def change_scrobble_rule(%ScrobbleRule{} = scrobble_rule, attrs \\ %{}) do
+    ScrobbleRule.changeset(scrobble_rule, attrs)
+  end
+
+  @doc """
+  Returns the list of enabled scrobble_rules.
+
+  ## Examples
+
+      iex> list_enabled_rules()
+      [%ScrobbleRule{}, ...]
+
+  """
+  def list_enabled_rules do
+    list_scrobble_rules(enabled: true)
+  end
+
+  @doc """
+  Applies an album rule to all matching scrobbled tracks.
+
+  ## Examples
+
+      iex> apply_album_rule(rule)
+      {:ok, 5}
+
+      iex> apply_album_rule(rule)
+      {:error, :invalid_rule_type}
+
+  """
+  def apply_album_rule(%ScrobbleRule{type: "album"} = rule) do
+    update_query =
+      from(t in Track,
+        where: fragment("json_extract(?, '$.title') = ?", t.album, ^rule.match_value),
+        update: [
+          set: [
+            album:
+              fragment(
+                "json_set(?, '$.musicbrainz_id', ?)",
+                t.album,
+                ^rule.target_musicbrainz_id
+              )
+          ]
+        ]
+      )
+
+    case Repo.update_all(update_query, []) do
+      {count, _} -> {:ok, count}
+      error -> {:error, error}
+    end
+  end
+
+  def apply_album_rule(%ScrobbleRule{type: type}) do
+    {:error, "Invalid rule type: #{type}. Expected 'album'"}
+  end
+
+  @doc """
+  Applies an artist rule to all matching scrobbled tracks.
+
+  ## Examples
+
+      iex> apply_artist_rule(rule)
+      {:ok, 10}
+
+      iex> apply_artist_rule(rule)
+      {:error, :invalid_rule_type}
+
+  """
+  def apply_artist_rule(%ScrobbleRule{type: "artist"} = rule) do
+    update_query =
+      from(t in Track,
+        where: fragment("json_extract(?, '$.name') = ?", t.artist, ^rule.match_value),
+        update: [
+          set: [
+            artist:
+              fragment(
+                "json_set(?, '$.musicbrainz_id', ?)",
+                t.artist,
+                ^rule.target_musicbrainz_id
+              )
+          ]
+        ]
+      )
+
+    case Repo.update_all(update_query, []) do
+      {count, _} -> {:ok, count}
+      error -> {:error, error}
+    end
+  end
+
+  def apply_artist_rule(%ScrobbleRule{type: type}) do
+    {:error, "Invalid rule type: #{type}. Expected 'artist'"}
+  end
+
+  @doc """
+  Applies a single rule based on its type.
+
+  ## Examples
+
+      iex> apply_rule(rule)
+      {:ok, 5}
+
+      iex> apply_rule(rule)
+      {:error, "Invalid rule type"}
+
+  """
+  def apply_rule(%ScrobbleRule{type: "album"} = rule) do
+    apply_album_rule(rule)
+  end
+
+  def apply_rule(%ScrobbleRule{type: "artist"} = rule) do
+    apply_artist_rule(rule)
+  end
+
+  def apply_rule(%ScrobbleRule{type: type}) do
+    {:error, "Invalid rule type: #{type}"}
+  end
+
+  @doc """
+  Applies all enabled rules.
+
+  ## Examples
+
+      iex> apply_all_rules()
+      {:ok, [{"album", 5}, {"artist", 10}]}
+
+  """
+  def apply_all_rules do
+    rules = list_enabled_rules()
+
+    results =
+      Enum.map(rules, fn rule ->
+        case apply_rule(rule) do
+          {:ok, count} -> {:ok, {rule.type, rule.match_value, count}}
+          {:error, reason} -> {:error, {rule.type, rule.match_value, reason}}
+        end
+      end)
+
+    {:ok, results}
+  rescue
+    e -> {:error, "Failed to apply rules: #{Exception.message(e)}"}
+  end
+
+  @doc """
+  Counts how many tracks would be affected by an album rule.
+
+  ## Examples
+
+      iex> count_album_matches(rule)
+      5
+
+  """
+  def count_album_matches(%ScrobbleRule{type: "album"} = rule) do
+    query =
+      from(t in Track,
+        where: fragment("json_extract(?, '$.title') = ?", t.album, ^rule.match_value),
+        select: count(t.scrobbled_at_uts)
+      )
+
+    Repo.one(query) || 0
+  end
+
+  def count_album_matches(%ScrobbleRule{type: type}) do
+    {:error, "Invalid rule type: #{type}. Expected 'album'"}
+  end
+
+  @doc """
+  Counts how many tracks would be affected by an artist rule.
+
+  ## Examples
+
+      iex> count_artist_matches(rule)
+      10
+
+  """
+  def count_artist_matches(%ScrobbleRule{type: "artist"} = rule) do
+    query =
+      from(t in Track,
+        where: fragment("json_extract(?, '$.name') = ?", t.artist, ^rule.match_value),
+        select: count(t.scrobbled_at_uts)
+      )
+
+    Repo.one(query) || 0
+  end
+
+  def count_artist_matches(%ScrobbleRule{type: type}) do
+    {:error, "Invalid rule type: #{type}. Expected 'artist'"}
+  end
+
+  @doc """
+  Counts how many tracks would be affected by a rule.
+
+  ## Examples
+
+      iex> count_rule_matches(rule)
+      5
+
+  """
+  def count_rule_matches(%ScrobbleRule{type: "album"} = rule) do
+    count_album_matches(rule)
+  end
+
+  def count_rule_matches(%ScrobbleRule{type: "artist"} = rule) do
+    count_artist_matches(rule)
+  end
+
+  def count_rule_matches(%ScrobbleRule{type: type}) do
+    {:error, "Invalid rule type: #{type}"}
+  end
+end

lib/music_library/scrobble_rules/scrobble_rule.ex

@@ -0,0 +1,59 @@
+defmodule MusicLibrary.ScrobbleRules.ScrobbleRule do
+  use Ecto.Schema
+
+  import Ecto.Changeset
+
+  @type t :: %__MODULE__{
+          id: integer() | nil,
+          type: String.t(),
+          match_value: String.t(),
+          target_musicbrainz_id: String.t(),
+          enabled: boolean(),
+          description: String.t() | nil,
+          inserted_at: NaiveDateTime.t() | nil,
+          updated_at: NaiveDateTime.t() | nil
+        }
+
+  @valid_types ~w(album artist)
+
+  schema "scrobble_rules" do
+    field :type, :string
+    field :match_value, :string
+    field :target_musicbrainz_id, :string
+    field :enabled, :boolean, default: true
+    field :description, :string
+
+    timestamps()
+  end
+
+  @doc false
+  def changeset(scrobble_rule, attrs) do
+    scrobble_rule
+    |> cast(attrs, [:type, :match_value, :target_musicbrainz_id, :enabled, :description])
+    |> validate_required([:type, :match_value, :target_musicbrainz_id])
+    |> validate_inclusion(:type, @valid_types)
+    |> validate_musicbrainz_id_format(:target_musicbrainz_id)
+  end
+
+  defp validate_musicbrainz_id_format(changeset, field) do
+    validate_change(changeset, field, fn _, value ->
+      case value do
+        "" ->
+          [{field, "cannot be empty"}]
+
+        value when is_binary(value) ->
+          if String.match?(
+               value,
+               ~r/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/i
+             ) do
+            []
+          else
+            [{field, "must be a valid MusicBrainz ID (UUID format)"}]
+          end
+
+        _ ->
+          [{field, "must be a string"}]
+      end
+    end)
+  end
+end

lib/music_library/scrobble_rules/worker.ex

@@ -0,0 +1,89 @@
+defmodule MusicLibrary.ScrobbleRules.Worker do
+  @moduledoc """
+  Oban worker that periodically applies all enabled scrobble rules.
+
+  This worker runs every 30 minutes and applies all enabled transformation rules
+  to the scrobbled_tracks table. It logs the results and handles errors gracefully.
+  """
+
+  use Oban.Worker, queue: :heavy_writes, max_attempts: 3
+
+  alias MusicLibrary.ScrobbleRules
+
+  require Logger
+
+  @impl Oban.Worker
+  def perform(%Oban.Job{args: _}) do
+    Logger.info("Starting scrobble rules application")
+
+    case ScrobbleRules.apply_all_rules() do
+      {:ok, results} ->
+        log_results(results)
+        :ok
+
+      {:error, reason} ->
+        Logger.error("Failed to apply scrobble rules: #{inspect(reason)}")
+        {:error, reason}
+    end
+  end
+
+  defp log_results(results) do
+    {applied, errors} =
+      Enum.split_with(results, fn
+        {:ok, _} -> true
+        {:error, _} -> false
+      end)
+
+    total_applied = length(applied)
+    total_errors = length(errors)
+
+    total_tracks_updated =
+      applied
+      |> Enum.map(fn {:ok, {_, _, count}} -> count end)
+      |> Enum.sum()
+
+    Logger.info("Scrobble rules application completed", %{
+      rules_applied: total_applied,
+      rules_failed: total_errors,
+      tracks_updated: total_tracks_updated
+    })
+
+    # Log individual rule results
+    Enum.each(applied, fn {:ok, {type, match_value, count}} ->
+      Logger.info("Applied #{type} rule", %{
+        match_value: match_value,
+        tracks_updated: count
+      })
+    end)
+
+    # Log errors
+    Enum.each(errors, fn {:error, {type, match_value, reason}} ->
+      Logger.error("Failed to apply #{type} rule", %{
+        match_value: match_value,
+        error: reason
+      })
+    end)
+  end
+
+  @doc """
+  Schedules the worker to run periodically.
+
+  This should be called during application startup to ensure
+  the worker runs automatically.
+  """
+  def schedule_periodic do
+    # Schedule to run every 30 minutes
+    __MODULE__.new(%{})
+    |> Oban.insert(schedule_in: {30, :minute})
+  end
+
+  @doc """
+  Triggers the worker to run immediately.
+
+  Useful for manual rule application or testing.
+  """
+  def run_now do
+    __MODULE__.new(%{})
+    |> Oban.insert()
+  end
+end