joeyates/imap-backup

This system is an IMAP email backup tool that synchronizes email data from remote servers to local storage using a modular, transactional architecture. It supports multiple download strategies, mirroring between accounts, and integrity checking, while providing utilities to export data to Thunderbird or import from CSV and other clients. The application features a comprehensive CLI for managing accounts, inspecting backups, and configuring settings, with robust support for containerized development and testing.

12 changes.

The project underwent a major version 17 overhaul, introducing a new Thor-based CLI, comprehensive internationalization, and a complete refactoring of the IMAP backup and restore logic into modular account and serializer components. This structural shift was accompanied by a strict upgrade to Ruby 3.2+, the removal of legacy entry points, and the addition of extensive unit test coverage for the new architecture.

18 changes.

This period focused on significantly expanding the imap-backup CLI with new commands for local inspection, integrity checking, and Thunderbird export, alongside an interactive setup interface. The work was heavily supported by the introduction of comprehensive RSpec test infrastructure, including feature specs, mock IMAP servers, and shared fixtures, to ensure reliability across these new features.

17 changes.

This period focused on expanding the tool's capabilities by introducing a single-account backup command and multiple IMAP download strategies, alongside new utility scripts for data migration. Significant effort was dedicated to comprehensive test coverage, adding unit and feature tests for the new CLI, setup wizards, and core client components. The work also included refactoring provider logic, fixing mboxrd serialization bugs, and establishing a containerized development environment.

Users can now run imap-backup in a containerized environment using the provided Containerfile and .containerignore. The image is built on Ruby 3.2.2 Alpine and executes the backup command with a configuration file at /config/imap-backup.json, allowing usage via Docker or Podman without local installation.

container · high confidence

Users can now export IMAP backup data into Thunderbird's native Mbox format. This change introduces a new MailboxExporter that writes messages to a local folder within a specified Thunderbird profile, handling profile validation, conflict detection (with a force option to overwrite), and proper formatting of email headers and bodies for Thunderbird compatibility.

lib/imap/backup/thunderbird · high confidence

The setup interface now provides interactive menus for configuring individual IMAP accounts and global application settings. Users can modify email addresses, passwords, server details, and connection options (including JSON-based settings) through a structured menu system. New capabilities include toggling mirror mode, managing folder blacklists, selecting specific folders for backup, adjusting multi-fetch sizes, and controlling seen-flag reset behavior. Global options allow changing the download strategy. The system also supports rotating account statuses (active, archived, offline) and deleting accounts, with validation to prevent duplicate email addresses and conflicting backup paths.

lib/imap/backup/setup · high confidence

Added a new \Imap::Backup::Mirror::Map\ class that manages the mapping between source and destination message UIDs. This component persists the mapping to a local JSON file, tracks UID validity for both source and destination accounts, and provides methods to look up equivalent UIDs in either direction. This enables the backup mirror to correctly correlate messages across IMAP servers even when UID assignments differ or change.

lib/imap/backup/mirror · high confidence

A new \backup\ command has been added to the \imap-backup\ CLI, allowing users to run a backup for a single account without relying on an existing configuration file. Users can specify the email address, IMAP server, and authentication method (plain password, environment variable, or password file) directly via command-line options. The command supports configuring the download strategy (delay or direct), selecting specific folders, setting a local storage path, and enabling mirror mode or seen-flag reset.

lib/imap/backup/cli/single · high confidence

The \lib/imap/backup/cli\ area introduces several new commands to the \imap-backup\ tool. Users can now inspect local backups using \local accounts\, \local folders\, \local list\, and \local show\ (with JSON output support), and verify backup integrity with \local check\ (which optionally deletes corrupt folders). A new \utils export-to-thunderbird\ command copies backed-up emails into a Thunderbird profile, and \utils ignore-history\ marks past emails as backed up to skip future downloads. Additionally, the \remote\ command now includes \capabilities\ and \namespaces\ subcommands for inspecting server settings, and the \stats\ command provides a folder-by-folder comparison of local versus remote email counts.

lib/imap/backup/cli · high confidence

Developers can now use a dedicated containerized setup in the \dev/containerized/\ directory to run the project against specific Ruby versions (including older, deprecated ones) alongside two pre-configured IMAP test servers. This environment includes a Docker Compose configuration, a Ruby base image with necessary dependencies, and a sample configuration file, allowing users to build, attach, and run tests or the \imap-backup\ tool in an isolated, reproducible container without needing to install those Ruby versions locally.

dev · high confidence

The contrib directory now includes example scripts to help users manage their imap-backup configuration and data. Users can bulk-import accounts from a CSV file using \import-accounts-from-csv\, extract specific email text from backups via \extract-email\, and migrate messages from a Thunderbird folder into imap-backup using \import-thunderbird-folder\. Additionally, a \jq\ script is provided to filter and list failures from the \local check\ command output.

contrib · high confidence

The bin directory now includes several new shell scripts to support development workflows: \bin/dev\ manages the local development environment via Podman Compose, while \bin/branch-coverage\, \bin/line-coverage\, \bin/branches-without-coverage\, and \bin/lines-without-coverage\ extract and filter code coverage data from SimpleCov JSON reports. Additional utilities include \bin/methods-without-parameter-documentation\ for checking YARD documentation gaps and \bin/unit-test-path\ for mapping source files to their corresponding spec files. The main \bin/imap-backup\ executable has been refactored to use the new CLI structure and conditionally activates CLI coverage during test runs.

bin · high confidence

The project has restructured its documentation and development tooling to separate end-user and developer resources. The main README now serves as an API documentation index pointing to the GitHub README for end-user usage, while a new ARCHITECTURE.md and AGENTS.md provide detailed developer guidance. A new .rspec file standardizes test execution with documentation formatting and random ordering, and the Rakefile now includes dedicated tasks for unit and feature specs alongside RuboCop linting. Additionally, a .mailmap file has been added to normalize contributor identities in the git history.

(repo-wide) · high confidence

The account modification menu now displays additional configuration details and supports new account settings. Users can see the account status (e.g., decommissioned) in the header, view the 'mirror mode' setting (which controls whether emails are kept or mirrored), and see the 'reset\_seen\_flags\_after\_fetch' flag if enabled. The menu also handles backslashes correctly in local paths and displays connection options as JSON. Additionally, the folder configuration now supports a 'folder blacklist' attribute, allowing users to exclude specific folders rather than including all.

lib/imap/backup/setup/account · high confidence

The IMAP backup serializer has been restructured into a modular architecture (Appender, DelayedMetadataSerializer, IntegrityChecker, etc.) to improve reliability and maintainability. Backups now use a new version 3.1 JSON metadata format that records UID validity and message flags, replacing the previous format. The system enforces data integrity through a new IntegrityChecker that validates mailbox and metadata consistency, and supports atomic operations via transactions that allow rolling back changes on error. Additionally, the serializer now handles UID validity conflicts by renaming backup folders with hyphens and ensures directory permissions are set correctly (excluding Windows).

lib/imap/backup/serializer · high confidence

The application has been upgraded to version 17.0.0-rc0, introducing a complete rewrite of the command-line interface using Thor and adding new commands such as 'copy' for transferring emails between accounts, 'local' for viewing local backup info, and 'stats' for reporting. Configuration management has been refactored into a dedicated Configuration class that supports global download strategies and improved folder handling, while the legacy Settings module has been removed. The release also includes new features like a provider-based setup wizard for automatic server configuration, internationalization support with locale files, and enhanced logging with password sanitization in debug output.

lib/imap/backup · high confidence

The \lib/imap/backup/account\ directory has been restructured into a set of focused classes to manage IMAP account operations. The new \Account::Backup\ class orchestrates the backup process, utilizing \Account::Locker\ to prevent concurrent access and \Account::BackupFolders\ to enumerate folders based on configuration. Individual folder backups are handled by \Account::FolderBackup\, which supports different download strategies and metadata serialization. The \Account::Restore\ class manages restoring data to the server, using \Account::FolderMapper\ to map local backup paths to remote folder names with configurable delimiters and prefixes. Additional classes like \Account::ClientFactory\ and \Account::LocalOnlyFolderDeleter\ support connection management and mirror-mode cleanup, respectively.

lib/imap/backup/account · high confidence

The IMAP backup client has been restructured to improve reliability and performance. A new \AutomaticLoginWrapper\ delays the IMAP login until the first actual command is issued, reducing unnecessary authentication overhead. The underlying \Default\ client now caches the currently selected or examined mailbox state, preventing redundant calls to the server when accessing the same folder repeatedly. Additionally, the client now supports reconnection logic and integrates provider-specific configurations for folder handling.

lib/imap/backup/client · high confidence

The lib/imap/backup.rb file, which previously served as the main entry point by requiring utility, account, downloader, settings, and version modules, has been deleted. This change removes the centralized loading mechanism for these components, likely as part of a broader refactoring to restructure how the IMAP backup library is initialized and organized.

lib/imap · high confidence

The email provider logic has been reorganized into the \Imap::Backup::Email::Provider\ namespace, introducing a base class that defines default behaviors (such as folder ignore tags and SSL settings) and specific provider classes for Apple Mail, Fastmail, GMail, Purelymail, and unknown providers. This change includes GMail-specific handling to skip folders tagged as 'Noselect', Apple Mail-specific configurations for IMAP host and root folder behavior, and Purelymail-specific flag handling, while ensuring all providers inherit from the new base structure.

lib/imap/backup/email/provider · high confidence

The setup interface now allows users to choose from multiple download strategies instead of using a single fixed approach. A new menu in the global options lets users select their preferred strategy, with the current selection clearly marked. This change replaces the previous single-strategy behavior, giving users more control over how emails are downloaded during the backup setup process.

_lib/imap/backup/setup/global\options · high confidence

The mboxrd message handler now correctly processes email bodies for storage and retrieval. It fixes a bug in the serialization logic that improperly quoted lines starting with 'From', ensuring compliance with the mboxrd format. Additionally, it introduces a specific deserialization path for legacy v3 data, correcting the over-quoting that occurred in previous versions so that old backups are restored accurately.

lib/imap/backup/email/mboxrd · high confidence

Added feature specs for export-to-thunderbird and ignore-history utilities; Added feature specs for imap-backup commands; Added feature specs for local backup commands; Added feature tests for account configuration setup; Added feature tests for account setup; Added feature tests for global download strategy configuration; Added feature tests for remote folders and namespaces commands; Added feature tests for single backup and mirror mode cleanup; Added performance benchmarking for IMAP backup operations; Added shared examples for logger options and configuration requirements; Added shared message fixtures for email testing; Added test support infrastructure for RSpec configuration and coverage; Added tests for email provider recognition logic; Added unit test coverage for core application components; Added unit tests for CLI commands and helpers; Added unit tests for IMAP client components; Added unit tests for Mboxrd message serialization and parsing; Added unit tests for Thunderbird mailbox export logic; Added unit tests for account backup, restore, and folder management components; Added unit tests for email provider implementations; Added unit tests for the CLI single backup command; Added unit tests for the account setup wizard components; Added unit tests for the serializer subsystem; Added unit tests for the text sanitizer; New test infrastructure for IMAP backup feature specs; Refactor test infrastructure and simplify coverage setup.

The gem now requires Ruby 3.2 or later and adds several runtime dependencies including i18n, locale, highline, logger, os, ostruct, sys-proctable, and thor (\~\> 1.1). It also updates the mail dependency to version 2.7.1 and requires net-imap \>= 0.3.2, while adding a dependency on the thunderbird gem (\~\> 0.6.0). Development dependencies have been moved to a separate group in the Gemfile, and the gemspec now explicitly lists MIT as the license and uses MFA-required metadata.

(dependencies) · high confidence

A new .gitkeep file was added to the tmp directory to ensure the directory is tracked by version control.

tmp · high confidence

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

• First survey — no prior run to compare against. CAI 66.

• Code Health 99
• Architecture 93
• Maturity 74
• Readiness 50
• Security 77

• 300 commits — 278 feature/other, 22 fixes

• lib/imap — 128 commits
• (root) — 58 commits
• spec/unit — 26 commits
• (repo) — 25 commits
• spec/features — 14 commits
• .github/README.md — 8 commits
• .github/workflows — 7 commits
• docs/TODO.md — 5 commits
• docs/plans — 4 commits
• docs/commands — 3 commits
• spec/support — 3 commits
• bin/imap-backup — 2 commits
• contrib/README.md — 2 commits
• contrib/extract-email — 2 commits
• docs/installation — 2 commits
• bin/branch-coverage — 1 commit
• bin/dev — 1 commit
• bin/line-coverage — 1 commit
• bin/methods-without-parameter-documentation — 1 commit
• bin/unit-test-path — 1 commit

• fix: Apply Rubocop fixes
• fix: Bugfix: correct name of parameter
• fix: Bugfix: don't try to activate coverage in container
• fix: Fix
• fix: Fix GitHub README links
• fix: Fix Github rendering in README.md
• fix: Fix Rubocop offenses
• fix: Fix Rubocop offenses
• fix: Fix Rubocop offenses
• fix: Fix Rubocop offenses
• fix: Fix add_extra_quote and clean_serialized regexes, rewrite mbox on v3 load
• fix: Fix add_extra_quote regex
• fix: Fix docs/installation/source.md
• fix: Fix duplicate flags in docker command
• fix: Fix test
• fix: Fix tests
• fix: Merge branch 'bugfix/fix-mboxrd-quote-serialization'
• fix: Merge branch 'fix/leagcy-mailbox-migration'
• fix: Merge branch 'fix/proctable-on-macos'
• fix: Merge pull request #190 from bentolor/fix/enable-tlsv1.3
• …and 280 more

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

joeyates/imap-backup was measured the same way every project in this corpus was: the same rubric, at a pinned commit, with the result published in full. Point a surveyor at a repository you know and see whether you agree with it.