Add database merge functionality

Implement full database merge support following KeePassXC's conceptual
algorithm with UUID-based matching and timestamp-based conflict resolution.

Features:
- MergeMode.STANDARD: Add and update entries/groups (safe default)
- MergeMode.SYNCHRONIZE: Also apply deletions from source
- Timestamp-based conflict resolution (newer modification wins)
- Losing version preserved in winner's history
- Location change tracking via location_changed timestamp
- Binary deduplication by SHA-256 hash
- Custom icon merging by UUID
- Recycle bin exclusion during merge
- DeletedObjects support for SYNCHRONIZE mode

Public API:
- Database.merge(source, mode=MergeMode.STANDARD) -> MergeResult
- MergeMode enum (STANDARD, SYNCHRONIZE)
- MergeResult dataclass with change counts and summary()
- MergeError exception for merge failures
- DeletedObject dataclass for tracking deletions

Includes 31 comprehensive tests covering basic merges, conflicts,
groups, history, binaries, custom icons, location changes, and
synchronize mode deletions.

Closes #54

Author: coreyleavitt

src/kdbxtool/__init__.py

@@ -42,6 +42,7 @@
     Kdbx3UpgradeRequired,
     KdbxError,
     KdfError,
+    MergeError,
     MissingCredentialsError,
     TwofishNotAvailableError,
     UnknownCipherError,
@@ -52,6 +53,7 @@
     YubiKeySlotError,
     YubiKeyTimeoutError,
 )
+from .merge import DeletedObject, MergeMode, MergeResult
 from .models import Attachment, Entry, Group, HistoryEntry, Times
 from .security import AesKdfConfig, Argon2Config, Cipher, KdfType
 from .security.keyfile import (
@@ -79,6 +81,10 @@
     "Times",
     "Cipher",
     "KdfType",
+    # Merge support
+    "MergeMode",
+    "MergeResult",
+    "DeletedObject",
     # Keyfile support
     "KeyFileVersion",
     "create_keyfile",
@@ -103,6 +109,7 @@
     "CredentialError",
     "InvalidPasswordError",
     "InvalidKeyFileError",
+    "MergeError",
     "MissingCredentialsError",
     "DatabaseError",
     "EntryNotFoundError",

src/kdbxtool/database.py

@@ -21,9 +21,12 @@
 from datetime import UTC, datetime, timedelta
 from pathlib import Path
 from types import TracebackType
-from typing import Protocol, cast
+from typing import TYPE_CHECKING, Protocol, cast
 from xml.etree.ElementTree import Element, SubElement, tostring
 
+if TYPE_CHECKING:
+    from .merge import DeletedObject
+
 from Cryptodome.Cipher import ChaCha20, Salsa20
 from defusedxml import ElementTree as DefusedET
 
@@ -170,6 +173,7 @@ class DatabaseSettings:
     history_max_items: int = 10
     history_max_size: int = 6 * 1024 * 1024  # 6 MiB
     custom_icons: dict[uuid_module.UUID, CustomIcon] = field(default_factory=dict)
+    deleted_objects: list["DeletedObject"] = field(default_factory=list)
 
 
 class Database:
@@ -307,6 +311,45 @@ def dump(self) -> str:
 
         return "\n".join(lines)
 
+    def merge(
+        self,
+        source: "Database",
+        *,
+        mode: "MergeMode" = None,
+    ) -> "MergeResult":
+        """Merge another database into this one.
+
+        Combines entries, groups, history, attachments, and custom icons
+        from the source database into this database using UUID-based
+        matching and timestamp-based conflict resolution.
+
+        Args:
+            source: Database to merge from (read-only)
+            mode: Merge mode (STANDARD or SYNCHRONIZE). Defaults to STANDARD.
+                - STANDARD: Add and update only, never deletes
+                - SYNCHRONIZE: Full sync including deletions
+
+        Returns:
+            MergeResult with counts and statistics about the merge
+
+        Raises:
+            MergeError: If merge cannot be completed
+
+        Example:
+            >>> target_db = Database.open("main.kdbx", password="secret")
+            >>> source_db = Database.open("branch.kdbx", password="secret")
+            >>> result = target_db.merge(source_db)
+            >>> print(f"Added {result.entries_added} entries")
+            >>> target_db.save()
+        """
+        from .merge import MergeMode, Merger, MergeResult
+
+        if mode is None:
+            mode = MergeMode.STANDARD
+
+        merger = Merger(self, source, mode=mode)
+        return merger.merge()
+
     @property
     def transformed_key(self) -> bytes | None:
         """Get the transformed key for caching.

src/kdbxtool/exceptions.py

@@ -317,3 +317,14 @@ def __init__(self) -> None:
             "Saving a KDBX3 database will upgrade it to KDBX4 format. "
             "Use save(allow_upgrade=True) to confirm, or save to a different file."
         )
+
+
+class MergeError(DatabaseError):
+    """Error during database merge operation.
+
+    Raised when a merge operation fails due to incompatible databases,
+    invalid state, or other merge-specific issues.
+    """
+
+    def __init__(self, message: str = "Merge operation failed") -> None:
+        super().__init__(message)