feat(archive): add yearly/monthly archive folder options

[fnune]

Fixes #900.
Resolves #8390.

Adds yearly and monthly archive folder organization matching Desktop's behavior. Eliminates the need to manually switch archive folders each year. Does this with an "Archive options" preference with three modes: Single folder, Yearly folders (Archive/2025), or Monthly folders (Archive/2025/03). Matches Desktop's two-setting approach and uses the same archiveGranularity property. Year/month subfolders are created automatically based on message date. Existing accounts default to single folder mode for backward compatibility.

Design decisions

Two settings: matches Desktop's "which folder?" + "how to organize?" rather than a flat list of "Archive-Yearly", "CustomFolder-Monthly", etc. Avoids combinatorial explosion and works with any base folder.

Automatic subfolder creation: year/month folders are created automatically based on granularity setting, not manually selected. This avoids yearly updates and matches Desktop behavior.

Defaults: new accounts default to yearly (matching Desktop). Existing accounts migrated to single folder to preserve current behavior.

Graceful degradation: if subfolder creation fails, messages are archived to the base archive folder rather than failing the operation entirely.

Uses account's folder path delimiter rather than assuming /, since some IMAP servers use . or other delimiters.

Potential follow-up

Issue #905 folder structure preservation, automatic yearly (or yearly + monthly) detection, translations...

Questions for reviewers

1. Should folder creation failures show user notifications, or is the current approach (graceful fallback to base folder with logging) acceptable?
2. Is PER_YEAR_ARCHIVE_FOLDERS the right default for new accounts (matching Desktop), with SINGLE_ARCHIVE_FOLDER for migrated accounts to preserve existing behavior?

Screenshots

[fnune]

I tried to match Thunderbird Desktop here but really there's only one option, so maybe this copy should be thought through once more. This is more stable if the area does get more features, and in that case "Archive options" would be fine, but currently it's a bit meh.

[fnune]

Hi @rafaeltonholo! Anything I can do to help get this chugging along? I keep refreshing this PR to see if anything's happened 😄

[rafaeltonholo]

Hi @rafaeltonholo! Anything I can do to help get this chugging along? I keep refreshing this PR to see if anything's happened 😄

Hi there! I started the review, but I didn't have time to finish it yet, and I forgot to send the comments I have already made. Sorry about that!

I'll try to finish the review this week, but here are the initial comments

[fnune]

Hi @rafaeltonholo, sorry it took me over a month to come back to this. I've been busy.

I've addressed the review feedback:

• Switched to kotlinx.datetime instead of java.util.Calendar
• Using account.folderPathDelimiter instead of the hardcoded default
• Refactored to remove @Suppress(ReturnCount) using idiomatic Kotlin

I also rebased onto main and bumped the migration to StorageMigrationTo30 since upstream took 29.

A couple of design questions I'd appreciate input on before finalizing:

1. When subfolder creation fails (e.g., Archive/2025 can't be created), the current implementation falls back to archiving in the base folder rather than failing. Is this acceptable, or should we notify the user?

2. New accounts default to PER_YEAR_ARCHIVE_FOLDERS (matching Desktop), while existing accounts get SINGLE_ARCHIVE_FOLDER via migration to preserve current behavior. Does this seem right?

[fnune]

Regarding the kotlinx.datetime suggestion for date handling:

I tried using kotlinx.datetime.Instant and kotlinx.datetime.Clock as suggested, but got a compilation error:

Unresolved reference 'System'

The rest of the codebase uses kotlin.time.Instant and kotlin.time.Clock instead (e.g., MessageItem.kt), so I followed that pattern:

@OptIn(ExperimentalTime::class)
private val LocalMessage.messageDate: LocalDate
    get() {
        val epochMillis = (internalDate ?: sentDate)?.time
        val timeZone = TimeZone.currentSystemDefault()
        val instant = epochMillis?.let { kotlin.time.Instant.fromEpochMilliseconds(it) }
            ?: Clock.System.now()
        return instant.toLocalDateTime(timeZone).date
    }

The logic is the same as your suggestion, just using kotlin.time for Instant/Clock.

[ryanleesipes]

Any chance we can review this and merge so it doesn't go stale? @jbott-tbird

[rafaeltonholo]

Any chance we can review this and merge so it doesn't go stale? @jbott-tbird

I will review this PR again later this week.

[dani-zilla]

We were waiting to request any changes until after the code freeze. It does look like there's a Spotless issue. You can run ./gradlew spotlessCheck to see what's wrong and either fix it yourself or run ./gradlew spotlessApply to automatically fix the issues. I do recommend doing the check first to make sure it won't mess anything up.

[github-actions]

Missing report label. Set exactly one of: report: include, report: exclude OR report: highlight.

[rafaeltonholo]

@fnune, @ryanleesipes, I have rebased this branch onto main and applied the necessary fixes. Additionally, I added functionality to disable the archive granularity option when the Archive folder is set to None.

@dani-zilla, please review at your convenience.

[dani-zilla]

I think this looks good. Seems to work as expected. To answer your questions:

Should folder creation failures show user notifications, or is the current approach (graceful fallback to base folder with logging) acceptable?

I do like the idea of showing a toast message, similar to the one we'd do if a user tries to move a message that is not yet synced with the server. Small an unobtrusive that tells them there was an issue with the archival process if they selected yearly or monthly, just because they may be upset to find it wasn't going into the expected folder once they finally figure it out.

Is PER_YEAR_ARCHIVE_FOLDERS the right default for new accounts (matching Desktop), with SINGLE_ARCHIVE_FOLDER for migrated accounts to preserve existing behavior?

This I think we should probably have set up to be a single archive folder by default for all new users as well. Just because it's unexpected behavior for most users to start creating archive folders, I would think. Perhaps only the default if they set a specific archive folder, as we do on desktop.