chore(release): bump version to 2.1.4 and update changelog with Library Inbound processing enhancements

- Added unit tests for manual and scheduled Library Inbound processing scenarios.
- Improved handling of media folders without `melodee.json` and refined timestamp-based scan selection.
- Updated `VersionPrefix` to 2.1.4 across all projects.

Author: sphildreth

docs/VERSION

@@ -1 +1 @@
-2.1.3
+2.1.4

docs/pages/changelog.md

@@ -23,6 +23,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.1.4] - 2026-06-16
+
 ### Added
 
 - Added public DecentDB usage and migration documentation covering Melodee's
@@ -34,6 +36,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Admin dashboard and login health warnings now open-check MusicBrainz and
   ArtistSearch DecentDB files and link to the migration guide when unsupported
   DecentDB file-format versions are detected.
+- Manual Library Inbound processing now bypasses the inbound root timestamp
+  shortcut so admin-triggered and force-mode scans inspect waiting releases.
+- Library Inbound scan selection now treats media folders without
+  `melodee.json` as unprocessed even when preserved file timestamps predate
+  the previous scan, while still avoiding churn for old folders that already
+  have Melodee metadata.
 
 ## [2.1.3] - 2026-06-15
 

src/Melodee.Blazor/Melodee.Blazor.csproj

@@ -16,7 +16,7 @@
 
     <!-- Auto-incrementing version -->
 
-    <VersionPrefix>2.1.3</VersionPrefix>
+    <VersionPrefix>2.1.4</VersionPrefix>
 
     <VersionSuffix>build$([System.DateTime]::UtcNow.ToString("yyyyMMddHHmmss"))</VersionSuffix>
     <AssemblyVersion>$(VersionPrefix).0</AssemblyVersion>

src/Melodee.Cli/Melodee.Cli.csproj

@@ -9,7 +9,7 @@
     <Deterministic>false</Deterministic>
     <NoWarn>$(NoWarn);NU1507</NoWarn>
 
-    <VersionPrefix>2.1.3</VersionPrefix>
+    <VersionPrefix>2.1.4</VersionPrefix>
 
     <VersionSuffix>build$([System.DateTime]::UtcNow.ToString("yyyyMMddHHmmss"))</VersionSuffix>
     <AssemblyVersion>$(VersionPrefix).0</AssemblyVersion>

src/Melodee.Common/Jobs/LibraryInboundProcessJob.cs

@@ -49,7 +49,7 @@ namespace Melodee.Common.Jobs;
 ///         <list type="bullet">
 ///             <item>Inbound library path not configured</item>
 ///             <item>Library is locked (IsLocked=true)</item>
-///             <item>No changes detected since last scan</item>
+///             <item>No changes detected since last scan for scheduled runs</item>
 ///         </list>
 ///     </para>
 ///     <para>
@@ -82,7 +82,7 @@ public override async Task Execute(IJobExecutionContext context)
             return;
         }
 
-        if (!inboundLibrary.NeedsScanning())
+        if (!ShouldBypassScanTimestamp(context) && !inboundLibrary.NeedsScanning())
         {
             Logger.Debug(
                 "[{JobName}] Inbound library does not need scanning. Directory last scanned [{LastScanAt}], Directory last write [{LastWriteTime}]",
@@ -153,6 +153,17 @@ private static bool IsManualTrigger(IJobExecutionContext context)
         return context.Trigger is not ICronTrigger;
     }
 
+    private static bool IsForceMode(IJobExecutionContext context)
+    {
+        return context.MergedJobDataMap.ContainsKey(MelodeeJobExecutionContext.ForceMode) &&
+               context.MergedJobDataMap.GetBoolean(MelodeeJobExecutionContext.ForceMode);
+    }
+
+    private static bool ShouldBypassScanTimestamp(IJobExecutionContext context)
+    {
+        return IsManualTrigger(context) || IsForceMode(context);
+    }
+
     private static bool ShouldChainToNextJob(IJobExecutionContext context)
     {
         if (!IsManualTrigger(context))

src/Melodee.Common/Melodee.Common.csproj

@@ -9,7 +9,7 @@
     <NoWarn>$(NoWarn);NU1507</NoWarn>
 
     <!-- Auto-incrementing version -->
-    <VersionPrefix>2.1.3</VersionPrefix>
+    <VersionPrefix>2.1.4</VersionPrefix>
     <VersionSuffix>build$([System.DateTime]::UtcNow.ToString("yyyyMMddHHmmss"))</VersionSuffix>
     <AssemblyVersion>$(VersionPrefix).0</AssemblyVersion>
     <FileVersion>$(VersionPrefix).0</FileVersion>

src/Melodee.Common/Models/Extensions/FileSystemDirectoryInfoExtensions.cs

@@ -323,11 +323,9 @@ public static IEnumerable<FileSystemDirectoryInfo> GetFileSystemDirectoryInfosTo
         {
             // Include directories with any files (not just media files) so that 
             // script-based deletion can evaluate and clean up non-media directories
-            var hasFiles = dir.EnumerateFiles("*.*", SearchOption.TopDirectoryOnly).Any();
-            var hasMediaFiles = hasFiles && dir.EnumerateFiles("*.*", SearchOption.TopDirectoryOnly)
-                .Any(x => FileHelper.IsFileMediaType(x.Extension));
+            var fileState = GetTopLevelFileProcessState(dir, modifiedSinceValue);
 
-            if (dir.LastWriteTimeUtc >= modifiedSinceValue && (hasMediaFiles || hasFiles))
+            if (ShouldProcessDirectory(dir, fileState, modifiedSinceValue))
             {
                 var fsDir = dir.ToFileSystemDirectoryInfo();
                 if (fsDir != null)
@@ -338,16 +336,61 @@ public static IEnumerable<FileSystemDirectoryInfo> GetFileSystemDirectoryInfosTo
         }
 
         // Check if the root directory itself has files (media or non-media)
-        var rootHasFiles = dirInfo.EnumerateFiles("*.*", SearchOption.TopDirectoryOnly).Any();
-        var rootHasMediaFiles = rootHasFiles && dirInfo.EnumerateFiles("*.*", SearchOption.TopDirectoryOnly)
-            .Any(x => x.LastWriteTimeUtc >= modifiedSinceValue && FileHelper.IsFileMediaType(x.Extension));
-
-        if (rootHasMediaFiles || (rootHasFiles && dirInfo.LastWriteTimeUtc >= modifiedSinceValue))
+        var rootFileState = GetTopLevelFileProcessState(dirInfo, modifiedSinceValue);
+        if (ShouldProcessDirectory(dirInfo, rootFileState, modifiedSinceValue))
         {
             yield return fileSystemDirectoryInfo;
         }
     }
 
+    private static DirectoryProcessFileState GetTopLevelFileProcessState(DirectoryInfo directoryInfo, DateTime modifiedSince)
+    {
+        var hasFiles = false;
+        var hasMediaFiles = false;
+        var hasModifiedMediaFiles = false;
+        var hasMelodeeJsonFiles = false;
+
+        foreach (var fileInfo in directoryInfo.EnumerateFiles("*.*", SearchOption.TopDirectoryOnly))
+        {
+            hasFiles = true;
+            var isMediaFile = FileHelper.IsFileMediaType(fileInfo.Extension);
+            hasMediaFiles |= isMediaFile;
+            hasModifiedMediaFiles |= isMediaFile && fileInfo.LastWriteTimeUtc >= modifiedSince;
+            hasMelodeeJsonFiles |= string.Equals(fileInfo.Name, Album.JsonFileName, StringComparison.OrdinalIgnoreCase);
+
+            if (hasMediaFiles && hasModifiedMediaFiles && hasMelodeeJsonFiles)
+            {
+                break;
+            }
+        }
+
+        return new DirectoryProcessFileState(hasFiles, hasMediaFiles, hasModifiedMediaFiles, hasMelodeeJsonFiles);
+    }
+
+    private static bool ShouldProcessDirectory(
+        DirectoryInfo directoryInfo,
+        DirectoryProcessFileState fileState,
+        DateTime modifiedSince)
+    {
+        if (!fileState.HasFiles)
+        {
+            return false;
+        }
+
+        if (directoryInfo.LastWriteTimeUtc >= modifiedSince || fileState.HasModifiedMediaFiles)
+        {
+            return true;
+        }
+
+        return fileState is { HasMediaFiles: true, HasMelodeeJsonFiles: false };
+    }
+
+    private readonly record struct DirectoryProcessFileState(
+        bool HasFiles,
+        bool HasMediaFiles,
+        bool HasModifiedMediaFiles,
+        bool HasMelodeeJsonFiles);
+
     public static (string, int) GetNextFileNameForType(this FileSystemDirectoryInfo fileSystemDirectoryInfo, string imageType)
     {
         var highestNumberFound = 0;

src/Melodee.Mql/Melodee.Mql.csproj

@@ -7,7 +7,7 @@
     <GenerateAssemblyInfo>true</GenerateAssemblyInfo>
     <NoWarn>$(NoWarn);NU1507</NoWarn>
 
-    <VersionPrefix>2.1.3</VersionPrefix>
+    <VersionPrefix>2.1.4</VersionPrefix>
     <VersionSuffix>build$([System.DateTime]::UtcNow.ToString("yyyyMMddHHmmss"))</VersionSuffix>
     <AssemblyVersion>$(VersionPrefix).0</AssemblyVersion>
     <FileVersion>$(VersionPrefix).0</FileVersion>

tests/Melodee.Tests.Common/Jobs/LibraryInboundProcessJobTests.cs

@@ -0,0 +1,60 @@
+using Melodee.Common.Jobs;
+using Moq;
+using Quartz;
+
+namespace Melodee.Tests.Common.Jobs;
+
+public class LibraryInboundProcessJobTests
+{
+    [Fact]
+    public void ShouldBypassScanTimestamp_WithManualContext_ReturnsTrue()
+    {
+        var context = new MelodeeJobExecutionContext(CancellationToken.None);
+
+        var result = InvokeShouldBypassScanTimestamp(context);
+
+        Assert.True(result);
+    }
+
+    [Fact]
+    public void ShouldBypassScanTimestamp_WithScheduledContext_ReturnsFalse()
+    {
+        var context = CreateScheduledContext(new JobDataMap());
+
+        var result = InvokeShouldBypassScanTimestamp(context);
+
+        Assert.False(result);
+    }
+
+    [Fact]
+    public void ShouldBypassScanTimestamp_WithScheduledForceModeContext_ReturnsTrue()
+    {
+        var jobDataMap = new JobDataMap
+        {
+            [MelodeeJobExecutionContext.ForceMode] = true
+        };
+        var context = CreateScheduledContext(jobDataMap);
+
+        var result = InvokeShouldBypassScanTimestamp(context);
+
+        Assert.True(result);
+    }
+
+    private static IJobExecutionContext CreateScheduledContext(JobDataMap jobDataMap)
+    {
+        var context = new Mock<IJobExecutionContext>();
+        context.SetupGet(x => x.Trigger).Returns(Mock.Of<ICronTrigger>());
+        context.SetupGet(x => x.MergedJobDataMap).Returns(jobDataMap);
+
+        return context.Object;
+    }
+
+    private static bool InvokeShouldBypassScanTimestamp(IJobExecutionContext context)
+    {
+        var method = typeof(LibraryInboundProcessJob).GetMethod(
+            "ShouldBypassScanTimestamp",
+            System.Reflection.BindingFlags.NonPublic | System.Reflection.BindingFlags.Static);
+
+        return (bool)method!.Invoke(null, [context])!;
+    }
+}

tests/Melodee.Tests.Common/Models/Extensions/FileSystemDirectoryInfoExtensionsTests.cs

@@ -1,6 +1,7 @@
 using FluentAssertions;
 using Melodee.Common.Models;
 using Melodee.Common.Models.Extensions;
+using NodaTime;
 
 namespace Melodee.Tests.Common.Models.Extensions;
 
@@ -311,6 +312,68 @@ public void AllAlbumMediaDirectories_WithMediaDirectories_ReturnsMediaDirs()
         mediaDirs.Should().Contain(d => d.Name == "CD2");
     }
 
+    [Fact]
+    public void GetFileSystemDirectoryInfosToProcess_WithOldUnprocessedMediaDirectory_ReturnsDirectory()
+    {
+        var root = CreateTestDirectory();
+        var albumPath = Path.Combine(root.FullName(), "Album");
+        Directory.CreateDirectory(albumPath);
+        var mediaPath = Path.Combine(albumPath, "song.mp3");
+        File.WriteAllText(mediaPath, "fake media");
+        var oldWriteTime = DateTime.UtcNow.AddDays(-10);
+        File.SetLastWriteTimeUtc(mediaPath, oldWriteTime);
+        Directory.SetLastWriteTimeUtc(albumPath, oldWriteTime);
+
+        var modifiedSince = Instant.FromDateTimeUtc(DateTime.UtcNow.AddDays(-1));
+        var directories = root.GetFileSystemDirectoryInfosToProcess(modifiedSince, SearchOption.AllDirectories).ToList();
+
+        directories.Should().ContainSingle(d => d.Name == "Album");
+    }
+
+    [Fact]
+    public void GetFileSystemDirectoryInfosToProcess_WithOldProcessedMediaDirectory_SkipsDirectory()
+    {
+        var root = CreateTestDirectory();
+        var albumPath = Path.Combine(root.FullName(), "Album");
+        Directory.CreateDirectory(albumPath);
+        var mediaPath = Path.Combine(albumPath, "song.mp3");
+        var metadataPath = Path.Combine(albumPath, Album.JsonFileName);
+        File.WriteAllText(mediaPath, "fake media");
+        File.WriteAllText(metadataPath, "{}");
+        var oldWriteTime = DateTime.UtcNow.AddDays(-10);
+        File.SetLastWriteTimeUtc(mediaPath, oldWriteTime);
+        File.SetLastWriteTimeUtc(metadataPath, oldWriteTime);
+        Directory.SetLastWriteTimeUtc(albumPath, oldWriteTime);
+
+        var modifiedSince = Instant.FromDateTimeUtc(DateTime.UtcNow.AddDays(-1));
+        var directories = root.GetFileSystemDirectoryInfosToProcess(modifiedSince, SearchOption.AllDirectories).ToList();
+
+        directories.Should().NotContain(d => d.Name == "Album");
+    }
+
+    [Fact]
+    public void GetFileSystemDirectoryInfosToProcess_WithModifiedMediaFileInOldProcessedDirectory_ReturnsDirectory()
+    {
+        var root = CreateTestDirectory();
+        var albumPath = Path.Combine(root.FullName(), "Album");
+        Directory.CreateDirectory(albumPath);
+        var mediaPath = Path.Combine(albumPath, "song.mp3");
+        var metadataPath = Path.Combine(albumPath, Album.JsonFileName);
+        File.WriteAllText(mediaPath, "fake media");
+        File.WriteAllText(metadataPath, "{}");
+        var oldWriteTime = DateTime.UtcNow.AddDays(-10);
+        var modifiedSince = DateTime.UtcNow.AddDays(-1);
+        File.SetLastWriteTimeUtc(metadataPath, oldWriteTime);
+        Directory.SetLastWriteTimeUtc(albumPath, oldWriteTime);
+        File.SetLastWriteTimeUtc(mediaPath, DateTime.UtcNow);
+
+        var directories = root
+            .GetFileSystemDirectoryInfosToProcess(Instant.FromDateTimeUtc(modifiedSince), SearchOption.AllDirectories)
+            .ToList();
+
+        directories.Should().ContainSingle(d => d.Name == "Album");
+    }
+
     [Fact]
     public void GetParent_DirectoryWithParent_ReturnsParent()
     {