autosync fix

Author: wpbonelli

.github/workflows/ci.yml

@@ -124,7 +124,7 @@ jobs:
         working-directory: modflow-devtools/autotest
         env:
           REPOS_PATH: ${{ github.workspace }}
-          MODFLOW_DEVTOOLS_NO_AUTO_SYNC: 1
+          MODFLOW_DEVTOOLS_AUTO_SYNC: 0
           TEST_DFN_PATH: ${{ github.workspace }}/modflow6/doc/mf6io/mf6ivar/dfn
         # use --dist loadfile to so tests requiring pytest-virtualenv run on the same worker
         run: uv run pytest -v -n auto --dist loadfile --durations 0 --ignore test_download.py --ignore test_models.py --ignore test_dfns_registry.py

docs/md/dev/dfns.md

@@ -476,7 +476,7 @@ status = get_sync_status()
 - **At install time**: Best-effort sync to default refs during package installation (fail silently on network errors)
 - **On first use**: If registry cache is empty for requested ref, attempt to sync before raising errors
 - **Lazy loading**: Don't sync until DFN access is actually requested
-- **Configurable**: Users can disable auto-sync via environment variable: `MODFLOW_DEVTOOLS_NO_AUTO_SYNC=1`
+- **Configurable (Experimental)**: Auto-sync is opt-in via environment variable: `MODFLOW_DEVTOOLS_AUTO_SYNC=1` (set to "1", "true", or "yes")
 
 ### Source repository integration
 
@@ -1295,7 +1295,7 @@ dfn.name  # attribute access
 5. Implement `sync_dfns()` function
 6. Add registry metadata caching with hash verification
 7. Implement version-controlled registry discovery
-8. Add auto-sync on first use (with opt-out via `MODFLOW_DEVTOOLS_NO_AUTO_SYNC`)
+8. Add auto-sync on first use (opt-in via `MODFLOW_DEVTOOLS_AUTO_SYNC` while experimental)
 9. **Implement `DfnSpec` dataclass** with `Mapping` protocol for single canonical hierarchical representation with flat dict access
 
 **CLI and module API** (depends on Registry infrastructure):

docs/md/dev/programs.md

@@ -509,7 +509,7 @@ status = get_sync_status()
 
 - **At install time**: Best-effort sync during package installation (fail silently on network errors)
 - **On first use**: If registry cache is empty, attempt to sync before raising errors
-- **Configurable**: Users can disable auto-sync via environment variable: `MODFLOW_DEVTOOLS_NO_AUTO_SYNC=1`
+- **Configurable (Experimental)**: Auto-sync is opt-in via environment variable: `MODFLOW_DEVTOOLS_AUTO_SYNC=1` (set to "1", "true", or "yes")
 
 #### Force semantics
 

docs/md/models.md

@@ -156,7 +156,7 @@ python -m modflow_devtools.models cp mf6/example/ex-gwf-twri01 /path/to/workspac
 ```
 
 The copy command:
-- Automatically attempts to sync registries before copying (unless `MODFLOW_DEVTOOLS_NO_AUTO_SYNC=1`)
+- Automatically attempts to sync registries before copying (if `MODFLOW_DEVTOOLS_AUTO_SYNC=1`)
 - Creates the workspace directory if it doesn't exist
 - Copies all input files for the specified model
 - Preserves subdirectory structure within the workspace
@@ -316,16 +316,16 @@ mf models clear --force
 
 ## Automatic Synchronization
 
-By default, `modflow-devtools` attempts to sync registries:
-- On first import (best-effort, fails silently on network errors)
-- When accessing models (unless `MODFLOW_DEVTOOLS_NO_AUTO_SYNC=1`)
-
-To disable auto-sync:
+Auto-sync is **opt-in** (experimental). To enable:
 
 ```bash
-export MODFLOW_DEVTOOLS_NO_AUTO_SYNC=1
+export MODFLOW_DEVTOOLS_AUTO_SYNC=1  # or "true" or "yes"
 ```
 
+When enabled, `modflow-devtools` attempts to sync registries:
+- On first access (best-effort, fails silently on network errors)
+- When accessing models via the API or CLI
+
 Then manually sync when needed:
 
 ```bash

docs/md/programs.md

@@ -347,17 +347,17 @@ mf programs install mf6 --force
 
 ## Automatic Synchronization
 
-By default, `modflow-devtools` attempts to sync registries:
-- On first import (best-effort, fails silently on network errors)
-- Before installation (unless `MODFLOW_DEVTOOLS_NO_AUTO_SYNC=1`)
-- Before listing available programs
-
-To disable auto-sync:
+Auto-sync is **opt-in** (experimental). To enable:
 
 ```bash
-export MODFLOW_DEVTOOLS_NO_AUTO_SYNC=1
+export MODFLOW_DEVTOOLS_AUTO_SYNC=1  # or "true" or "yes"
 ```
 
+When enabled, `modflow-devtools` attempts to sync registries:
+- On first access (best-effort, fails silently on network errors)
+- Before installation
+- Before listing available programs
+
 Then manually sync when needed:
 
 ```bash

modflow_devtools/dfns/registry.py

@@ -734,7 +734,7 @@ def get_sync_status(source: str = "modflow6") -> dict[str, bool]:
 def get_registry(
     source: str = "modflow6",
     ref: str = "develop",
-    auto_sync: bool = True,
+    auto_sync: bool = False,
     path: str | PathLike | None = None,
 ) -> DfnRegistry:
     """
@@ -747,8 +747,9 @@ def get_registry(
     ref : str, optional
         Git ref (branch, tag, or commit hash). Default is "develop".
     auto_sync : bool, optional
-        If True and registry is not cached, automatically sync. Default is True.
-        Can be disabled via MODFLOW_DEVTOOLS_NO_AUTO_SYNC environment variable.
+        If True and registry is not cached, automatically sync. Default is False
+        (opt-in while experimental). Can be enabled via MODFLOW_DEVTOOLS_AUTO_SYNC
+        environment variable (set to "1", "true", or "yes").
         Ignored when path is provided.
     path : str or PathLike, optional
         Path to a local directory containing DFN files. If provided, returns
@@ -775,9 +776,9 @@ def get_registry(
     if path is not None:
         return LocalDfnRegistry(path=Path(path), source=source, ref=ref)
 
-    # Check for auto-sync opt-out
-    if os.environ.get("MODFLOW_DEVTOOLS_NO_AUTO_SYNC", "").lower() in ("1", "true", "yes"):
-        auto_sync = False
+    # Check for auto-sync opt-in (experimental - off by default)
+    if os.environ.get("MODFLOW_DEVTOOLS_AUTO_SYNC", "").lower() in ("1", "true", "yes"):
+        auto_sync = True
 
     registry = RemoteDfnRegistry(source=source, ref=ref)
 

modflow_devtools/models/__init__.py

@@ -1322,13 +1322,19 @@ def get_default_registry():
     This allows the module to import successfully even if the cache
     is empty, with a clear error message on first use.
 
+    Auto-sync can be enabled via MODFLOW_DEVTOOLS_AUTO_SYNC environment variable
+    (currently opt-in while experimental). Set to "1", "true", or "yes" to enable.
+
     Returns
     -------
     PoochRegistry
         The default model registry
     """
     global _default_registry_cache
     if _default_registry_cache is None:
+        # Opt-in auto-sync (experimental - off by default)
+        if os.environ.get("MODFLOW_DEVTOOLS_AUTO_SYNC", "").lower() in ("1", "true", "yes"):
+            _try_best_effort_sync()
         _default_registry_cache = PoochRegistry(base_url=_DEFAULT_BASE_URL, env=_DEFAULT_ENV)
     return _default_registry_cache
 

modflow_devtools/models/__main__.py

@@ -108,7 +108,7 @@ def cmd_sync(args):
 def cmd_info(args):
     """Info command handler."""
     # Attempt auto-sync before showing info (unless disabled)
-    if not os.environ.get("MODFLOW_DEVTOOLS_NO_AUTO_SYNC"):
+    if os.environ.get("MODFLOW_DEVTOOLS_AUTO_SYNC", "").lower() in ("1", "true", "yes"):
         _try_best_effort_sync()
 
     config = ModelSourceConfig.load()
@@ -176,7 +176,7 @@ def cmd_info(args):
 def cmd_list(args):
     """List command handler."""
     # Attempt auto-sync before listing (unless disabled)
-    if not os.environ.get("MODFLOW_DEVTOOLS_NO_AUTO_SYNC"):
+    if os.environ.get("MODFLOW_DEVTOOLS_AUTO_SYNC", "").lower() in ("1", "true", "yes"):
         _try_best_effort_sync()
 
     cached = _DEFAULT_CACHE.list()
@@ -285,7 +285,7 @@ def cmd_clear(args):
 def cmd_copy(args):
     """Copy command handler."""
     # Attempt auto-sync before copying (unless disabled)
-    if not os.environ.get("MODFLOW_DEVTOOLS_NO_AUTO_SYNC"):
+    if os.environ.get("MODFLOW_DEVTOOLS_AUTO_SYNC", "").lower() in ("1", "true", "yes"):
         _try_best_effort_sync()
 
     from . import copy_to

modflow_devtools/programs/__main__.py

@@ -139,7 +139,7 @@ def cmd_info(args):
 def cmd_list(args):
     """List command handler."""
     # Attempt auto-sync before listing (unless disabled)
-    if not os.environ.get("MODFLOW_DEVTOOLS_NO_AUTO_SYNC"):
+    if os.environ.get("MODFLOW_DEVTOOLS_AUTO_SYNC", "").lower() in ("1", "true", "yes"):
         _try_best_effort_sync()
 
     cached = _DEFAULT_CACHE.list()
@@ -193,7 +193,7 @@ def cmd_list(args):
 def cmd_install(args):
     """Install command handler."""
     # Attempt auto-sync before installation (unless disabled)
-    if not os.environ.get("MODFLOW_DEVTOOLS_NO_AUTO_SYNC"):
+    if os.environ.get("MODFLOW_DEVTOOLS_AUTO_SYNC", "").lower() in ("1", "true", "yes"):
         _try_best_effort_sync()
 
     # Parse program@version syntax if provided