Move implicit config from storage to pair and add conflict resolution

Use conflict_resolution parameter to determine behavior when both
'create' and 'delete' are specified in implicit.

When collection exists in A but not B:
  - 'a wins': create in B, delete from A
  - 'b wins': create in A, delete from B
  - No resolution: raise clear error

This resolves the ambiguity issue raised in PR pimutils#869 by using the
existing conflict_resolution mechanism to make the behavior predictable
and controllable.

Author: samsonjs

CHANGELOG.rst

@@ -56,6 +56,14 @@ Version 0.19.0
 - Add a new ``showconfig`` status. This prints *some* configuration values as
   JSON. This is intended to be used by external tools and helpers that interact
   with ``vdirsyncer``, and considered experimental.
+- **BREAKING**: Improved ``implicit`` parameter behavior when both "create" and 
+  "delete" are specified. Previously, the behavior in ambiguous cases (when a 
+  collection exists on one side but not the other) was undefined. Now, the 
+  ``conflict_resolution`` parameter is used to determine the action: "a wins" 
+  creates missing collections in B and deletes extra collections from A, while 
+  "b wins" does the opposite. If both "create" and "delete" are specified 
+  without ``conflict_resolution``, vdirsyncer will raise an error instead of 
+  making unpredictable choices.
 - Update TLS-related tests that were failing due to weak MDs. :gh:`903`
 - ``pytest-httpserver`` and ``trustme`` are now required for tests.
 - ``pytest-localserver`` is no longer required for tests.
@@ -73,12 +81,14 @@ Version 0.19.0
 - The ``plist`` for macOS has been dropped. It was broken and homebrew
   generates their own based on package metadata. macOS users are encouraged to
   use that as a reference.
+- Add ``implicit`` option to the :ref:`pair section <pair_config>`. It implicitly
+  creates and deletes collections in the destinations, when new collections are
+  created/deleted in the source. The deletion is implemented only for the
+  "filesystem" storage. This respects your `conflict_resolution` configuration
+  and shows an error when not configured or set to run a command.
+  See :ref:`implicit docs <implicit_def>` for details.
 
 .. _etesync-dav: https://github.com/etesync/etesync-dav
-- Add ``implicit`` option to storage section.  It creates/deletes implicitly
-  collections in the destinations, when new collections are created/deleted
-  in the source. The deletion is implemented only for the "filesystem" storage.
-  See :ref:`storage_config`.
 
 Changes to SSL configuration
 ----------------------------

CLAUDE.md

@@ -0,0 +1,102 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+vdirsyncer is a command-line tool for synchronizing calendars and addressbooks between various servers and the local filesystem. It's essentially "OfflineIMAP for calendars and contacts" - syncing CalDAV and CardDAV servers with local vdir directories.
+
+## Development Commands
+
+### Setup and Installation
+```bash
+make install-dev     # Install in development mode with test dependencies
+```
+
+### Testing
+```bash
+make test            # Run all tests
+make style           # Check code style with flake8
+make test-storage    # Run only storage tests
+make test-unit       # Run only unit tests  
+make test-system     # Run only system tests
+
+# Test against specific DAV servers:
+make DAV_SERVER=radicale test
+make DAV_SERVER=xandikos test
+make DAV_SERVER=baikal test
+make DAV_SERVER=davical test
+make DAV_SERVER=fastmail test
+make DAV_SERVER=icloud test
+
+# Run specific test file:
+pytest tests/unit/sync/test_sync.py
+pytest tests/unit/sync/test_sync.py::test_name
+```
+
+### Documentation
+```bash
+make docs            # Build documentation
+make install-docs    # Install docs dependencies
+```
+
+### Release Process
+```bash
+make release         # Build and upload release to PyPI
+```
+
+## Architecture
+
+### Core Components
+
+1. **Storage Layer** (`vdirsyncer/storage/`)
+   - `base.py`: Abstract base classes defining storage interface
+   - `filesystem.py`: Local filesystem storage using vdir format
+   - `dav.py`: CalDAV/CardDAV server storage
+   - `google.py`: Google Calendar/Contacts storage
+   - `http.py`: Read-only HTTP storage
+   - `singlefile.py`: Single .ics/.vcf file storage
+   - `memory.py`: In-memory storage for testing
+
+2. **Sync Engine** (`vdirsyncer/sync/`)
+   - `__init__.py`: Core sync algorithm based on OfflineIMAP
+   - `status.py`: Tracks sync state between storages
+   - `exceptions.py`: Sync-specific exceptions
+
+3. **CLI** (`vdirsyncer/cli/`)
+   - `config.py`: Configuration file parsing and validation
+   - `discover.py`: Collection discovery implementation
+   - `tasks.py`: Main CLI commands (sync, discover, etc.)
+   - `utils.py`: CLI utilities and helpers
+
+4. **Core Utilities**
+   - `metasync.py`: Metadata synchronization
+   - `repair.py`: Item repair functionality
+   - `http.py`: HTTP session management with auth
+   - `vobject.py`: vCard/iCalendar parsing utilities
+
+### Key Design Patterns
+
+- **Storage Interface**: All storage backends implement abstract methods from `Storage` base class
+- **Async Architecture**: Uses asyncio throughout for concurrent operations
+- **Item-based Sync**: Each calendar event or contact is an "item" with a unique href
+- **Conflict Resolution**: Configurable strategies (a wins, b wins, etc.) 
+- **Collection Mapping**: Pairs of collections are configured and synced independently
+
+### Configuration
+
+Config files are in INI format with three section types:
+- `[general]`: Global settings
+- `[storage <name>]`: Storage backend definitions  
+- `[pair <name>]`: Sync pair configuration linking two storages
+
+## Code Style
+
+- Python 3.7+ required
+- Uses Black formatter with 88 character line limit
+- Type hints encouraged but not required
+- Follow PEP 8 with Black's modifications
+
+## Current Feature Branch
+
+Currently on `storage-implicit-conflict-resolution` branch working on implicit collection creation during sync operations.

docs/config.rst

@@ -128,6 +128,36 @@ Pair Section
 
   The ``conflict_resolution`` parameter applies for these properties too.
 
+.. _implicit_def:
+
+- ``implicit``: Opt into implicitly creation and/or deleting collections. Example::
+
+      implicit = "create"
+
+  or
+
+      implicit = ["create", "delete"]
+
+  When a new collection is created on the source, and the value includes "create",
+  new collections are created in the destination without asking questions. When
+  the value includes "delete" and collections are removed from the source, they're
+  automatically removed from the destination as well.
+
+  The value can be a string or an array of strings.
+
+  **Conflict Resolution**: When both "create" and "delete" are specified, there
+  can be ambiguous situations where a collection exists on one side but not the
+  other. In these cases, vdirsyncer uses the ``conflict_resolution`` parameter
+  to determine the action:
+
+  - ``conflict_resolution = "a wins"``: Collections missing in A are created;
+    collections missing in B are deleted from A.
+  - ``conflict_resolution = "b wins"``: Collections missing in B are created;
+    collections missing in A are deleted from B.
+
+  If both "create" and "delete" are specified but no ``conflict_resolution`` is
+  set, vdirsyncer will raise an error when encountering ambiguous situations.
+
 .. _storage_config:
 
 Storage Section
@@ -381,8 +411,6 @@ Local
       #post_hook = null
       #pre_deletion_hook = null
       #fileignoreext = ".tmp"
-      #implicit = "create"
-      #implicit = ["create", "delete"]
 
     Can be used with `khal <http://lostpackets.de/khal/>`_. See :doc:`vdir` for
     a more formal description of the format.
@@ -407,12 +435,7 @@ Local
         The command will be called with the path of the deleted file.
     :param fileeignoreext: The file extention to ignore. It is only useful
         if fileext is set to the empty string. The default is ``.tmp``.
-    :param implicit: When a new collection is created on the source, and the
-        value is "create", create the collection in the destination without
-        asking questions.  When the value is "delete" and a collection
-        is removed on the source, remove it in the destination.  The value
-        can be a string or an array of strings.  The deletion is implemented
-        only for the "filesystem" storage.
+
 
 .. storage:: singlefile
 

tests/storage/servers/davical/__init__.py

@@ -39,10 +39,11 @@ async def inner(collection="test"):
                 args = self.storage_class.create_collection(
                     collection + str(uuid.uuid4()), **davical_args
                 )
-                s = self.storage_class(**args)
-                if not list(s.list()):
-                    # See: https://stackoverflow.com/a/33984811
-                    request.addfinalizer(lambda x=s: x.session.request("DELETE", ""))
+                storage = self.storage_class(**args)
+                if not list(storage.list()):
+                    request.addfinalizer(
+                        lambda s=storage: s.session.request("DELETE", "")
+                    )
                     return args
 
             raise RuntimeError("Failed to find free collection.")

tests/system/cli/test_config.py

@@ -62,13 +62,8 @@ def test_read_config(read_config):
             "yesno": False,
             "number": 42,
             "instance_name": "bob_a",
-            "implicit": [],
-        },
-        "bob_b": {
-            "type": "carddav",
-            "instance_name": "bob_b",
-            "implicit": [],
         },
+        "bob_b": {"type": "carddav", "instance_name": "bob_b"},
     }
 
 
@@ -227,3 +222,156 @@ def test_validate_collections_param():
     x([["c", None, "b"]])
     x([["c", "a", None]])
     x([["c", None, None]])
+
+
+def test_invalid_implicit_type(read_config):
+    expected_message = "`implicit` parameter must be a list, string, or absent"
+    with pytest.raises(exceptions.UserError) as excinfo:
+        read_config(
+            """
+            [general]
+            status_path = "/tmp/status/"
+
+            [pair my_pair]
+            a = "my_a"
+            b = "my_b"
+            collections = null
+            implicit = 42
+
+            [storage my_a]
+            type = "filesystem"
+            path = "{base}/path_a/"
+            fileext = ".txt"
+
+            [storage my_b]
+            type = "filesystem"
+            path = "{base}/path_b/"
+            fileext = ".txt"
+            """
+        )
+
+    assert expected_message in str(excinfo.value)
+
+
+def test_invalid_implicit_member(read_config):
+    expected_message = "`implicit` parameter, position 0: must be one of"
+    with pytest.raises(exceptions.UserError) as excinfo:
+        read_config(
+            """
+            [general]
+            status_path = "/tmp/status/"
+
+            [pair my_pair]
+            a = "my_a"
+            b = "my_b"
+            collections = null
+            implicit = ["invalid"]
+
+            [storage my_a]
+            type = "filesystem"
+            path = "{base}/path_a/"
+            fileext = ".txt"
+
+            [storage my_b]
+            type = "filesystem"
+            path = "{base}/path_b/"
+            fileext = ".txt"
+            """
+        )
+
+    assert expected_message in str(excinfo.value)
+
+
+def test_implicit_create_delete_with_conflict_resolution(read_config):
+    """Test that implicit create and delete works with conflict resolution."""
+    # This should not raise an error
+    errors, c = read_config(
+        """
+        [general]
+        status_path = "/tmp/status/"
+
+        [pair my_pair]
+        a = "my_a"
+        b = "my_b"
+        collections = ["from a", "from b"]
+        implicit = ["create", "delete"]
+        conflict_resolution = "a wins"
+
+        [storage my_a]
+        type = "filesystem"
+        path = "{base}/path_a/"
+        fileext = ".txt"
+
+        [storage my_b]
+        type = "filesystem"
+        path = "{base}/path_b/"
+        fileext = ".txt"
+        """
+    )
+    
+    assert not errors
+    pair = c.pairs["my_pair"]
+    assert pair.implicit == ["create", "delete"]
+    assert pair.conflict_resolution == "a wins"
+
+
+def test_implicit_create_delete_without_conflict_resolution(read_config):
+    """Test that implicit create and delete without conflict resolution still works in config parsing."""
+    # Config parsing should succeed, but discovery should fail
+    errors, c = read_config(
+        """
+        [general]
+        status_path = "/tmp/status/"
+
+        [pair my_pair]
+        a = "my_a"
+        b = "my_b"
+        collections = ["from a", "from b"]
+        implicit = ["create", "delete"]
+
+        [storage my_a]
+        type = "filesystem"
+        path = "{base}/path_a/"
+        fileext = ".txt"
+
+        [storage my_b]
+        type = "filesystem"
+        path = "{base}/path_b/"
+        fileext = ".txt"
+        """
+    )
+    
+    assert not errors
+    pair = c.pairs["my_pair"]
+    assert pair.implicit == ["create", "delete"]
+    assert pair.conflict_resolution is None
+
+
+def test_implicit_create_only(read_config):
+    """Test that implicit create without delete works without conflict resolution."""
+    errors, c = read_config(
+        """
+        [general]
+        status_path = "/tmp/status/"
+
+        [pair my_pair]
+        a = "my_a"
+        b = "my_b"
+        collections = ["from a", "from b"]
+        implicit = ["create"]
+
+        [storage my_a]
+        type = "filesystem"
+        path = "{base}/path_a/"
+        fileext = ".txt"
+
+        [storage my_b]
+        type = "filesystem"
+        path = "{base}/path_b/"
+        fileext = ".txt"
+        """
+    )
+    
+    assert not errors
+    pair = c.pairs["my_pair"]
+    assert pair.implicit == ["create"]

tests/system/utils/test_main.py

@@ -22,7 +22,7 @@ def test_get_storage_init_args():
     from vdirsyncer.storage.memory import MemoryStorage
 
     all, required = utils.get_storage_init_args(MemoryStorage)
-    assert all == {"fileext", "collection", "read_only", "instance_name", "implicit"}
+    assert all == {"fileext", "collection", "read_only", "instance_name"}
     assert not required