cli/fmt(feat[--all]): Add --all flag to format all discovered configs

why: Users need a way to format all their vcspull configuration files at once,
similar to how sync discovers and processes all configs.

what:
- Add --all flag to fmt command argument parser
- Refactor format_config_file() into format_single_config() for individual files
- Update format_config_file() to handle both single file and --all modes
- Discover configs using find_config_files(include_home=True) when --all is used
- Include local .vcspull.yaml/json files in current directory
- Add clear progress reporting showing all files found and their status
- Add summary at the end showing success count
- Update existing tests to pass new format_all parameter
- Add comprehensive test for --all functionality with mocked config discovery
- Fix type annotations for test helper functions

refs: Enhancement to make vcspull fmt more powerful for managing multiple configs

Author: tony

src/vcspull/cli/__init__.py

@@ -145,4 +145,4 @@ def cli(_args: list[str] | None = None) -> None:
             yes=args.yes,
         )
     elif args.subparser_name == "fmt":
-        format_config_file(args.config, args.write)
+        format_config_file(args.config, args.write, args.all)

src/vcspull/cli/fmt.py

@@ -10,7 +10,7 @@
 from colorama import Fore, Style
 
 from vcspull._internal.config_reader import ConfigReader
-from vcspull.config import find_home_config_files, save_config_yaml
+from vcspull.config import find_config_files, find_home_config_files, save_config_yaml
 
 if t.TYPE_CHECKING:
     import argparse
@@ -33,6 +33,11 @@ def create_fmt_subparser(parser: argparse.ArgumentParser) -> None:
         action="store_true",
         help="Write formatted configuration back to file",
     )
+    parser.add_argument(
+        "--all",
+        action="store_true",
+        help="Format all discovered config files (home, config dir, and current dir)",
+    )
 
 
 def normalize_repo_config(repo_data: t.Any) -> dict[str, t.Any]:
@@ -118,45 +123,24 @@ def format_config(config_data: dict[str, t.Any]) -> tuple[dict[str, t.Any], int]
     return formatted, changes
 
 
-def format_config_file(
-    config_file_path_str: str | None,
+def format_single_config(
+    config_file_path: pathlib.Path,
     write: bool,
-) -> None:
-    """Format a vcspull configuration file.
+) -> bool:
+    """Format a single vcspull configuration file.
 
     Parameters
     ----------
-    config_file_path_str : str | None
-        Path to config file, or None to use default
+    config_file_path : pathlib.Path
+        Path to config file
     write : bool
         Whether to write changes back to file
-    """
-    # Determine config file
-    config_file_path: pathlib.Path
-    if config_file_path_str:
-        config_file_path = pathlib.Path(config_file_path_str).expanduser().resolve()
-    else:
-        home_configs = find_home_config_files(filetype=["yaml"])
-        if not home_configs:
-            # Try local .vcspull.yaml
-            local_config = pathlib.Path.cwd() / ".vcspull.yaml"
-            if local_config.exists():
-                config_file_path = local_config
-            else:
-                log.error(
-                    "%s✗%s No configuration file found. Create .vcspull.yaml first.",
-                    Fore.RED,
-                    Style.RESET_ALL,
-                )
-                return
-        elif len(home_configs) > 1:
-            log.error(
-                "Multiple home config files found, please specify one with -c/--config",
-            )
-            return
-        else:
-            config_file_path = home_configs[0]
 
+    Returns
+    -------
+    bool
+        True if formatting was successful, False otherwise
+    """
     # Check if file exists
     if not config_file_path.exists():
         log.error(
@@ -167,7 +151,7 @@ def format_config_file(
             config_file_path,
             Style.RESET_ALL,
         )
-        return
+        return False
 
     # Load existing config
     try:
@@ -177,12 +161,12 @@ def format_config_file(
                 "Config file %s is not a valid YAML dictionary.",
                 config_file_path,
             )
-            return
+            return False
     except Exception:
         log.exception("Error loading config from %s", config_file_path)
         if log.isEnabledFor(logging.DEBUG):
             traceback.print_exc()
-        return
+        return False
 
     # Format the configuration
     formatted_config, change_count = format_config(raw_config)
@@ -196,7 +180,7 @@ def format_config_file(
             config_file_path,
             Style.RESET_ALL,
         )
-        return
+        return True
 
     # Show what would be changed
     log.info(
@@ -280,6 +264,7 @@ def format_config_file(
             log.exception("Error saving formatted config to %s", config_file_path)
             if log.isEnabledFor(logging.DEBUG):
                 traceback.print_exc()
+            return False
     else:
         log.info(
             "\n%s→%s Run with %s--write%s to apply these formatting changes.",
@@ -288,3 +273,117 @@ def format_config_file(
             Fore.CYAN,
             Style.RESET_ALL,
         )
+    
+    return True
+
+
+def format_config_file(
+    config_file_path_str: str | None,
+    write: bool,
+    format_all: bool = False,
+) -> None:
+    """Format vcspull configuration file(s).
+
+    Parameters
+    ----------
+    config_file_path_str : str | None
+        Path to config file, or None to use default
+    write : bool
+        Whether to write changes back to file
+    format_all : bool
+        If True, format all discovered config files
+    """
+    if format_all:
+        # Format all discovered config files
+        config_files = find_config_files(include_home=True)
+        
+        # Also check for local .vcspull.yaml
+        local_yaml = pathlib.Path.cwd() / ".vcspull.yaml"
+        if local_yaml.exists() and local_yaml not in config_files:
+            config_files.append(local_yaml)
+        
+        # Also check for local .vcspull.json
+        local_json = pathlib.Path.cwd() / ".vcspull.json"
+        if local_json.exists() and local_json not in config_files:
+            config_files.append(local_json)
+        
+        if not config_files:
+            log.error(
+                "%s✗%s No configuration files found.",
+                Fore.RED,
+                Style.RESET_ALL,
+            )
+            return
+        
+        log.info(
+            "%si%s Found %s%d%s configuration %s to format:",
+            Fore.CYAN,
+            Style.RESET_ALL,
+            Fore.YELLOW,
+            len(config_files),
+            Style.RESET_ALL,
+            "file" if len(config_files) == 1 else "files",
+        )
+        
+        for config_file in config_files:
+            log.info(
+                "  %s•%s %s%s%s",
+                Fore.BLUE,
+                Style.RESET_ALL,
+                Fore.CYAN,
+                config_file,
+                Style.RESET_ALL,
+            )
+        
+        log.info("")  # Empty line for readability
+        
+        success_count = 0
+        for config_file in config_files:
+            if format_single_config(config_file, write):
+                success_count += 1
+        
+        # Summary
+        if success_count == len(config_files):
+            log.info(
+                "\n%s✓%s All %d configuration files processed successfully.",
+                Fore.GREEN,
+                Style.RESET_ALL,
+                len(config_files),
+            )
+        else:
+            log.info(
+                "\n%si%s Processed %d/%d configuration files successfully.",
+                Fore.CYAN,
+                Style.RESET_ALL,
+                success_count,
+                len(config_files),
+            )
+    else:
+        # Format single config file
+        if config_file_path_str:
+            config_file_path = pathlib.Path(config_file_path_str).expanduser().resolve()
+        else:
+            home_configs = find_home_config_files(filetype=["yaml"])
+            if not home_configs:
+                # Try local .vcspull.yaml
+                local_config = pathlib.Path.cwd() / ".vcspull.yaml"
+                if local_config.exists():
+                    config_file_path = local_config
+                else:
+                    log.error(
+                        "%s✗%s No configuration file found. "
+                        "Create .vcspull.yaml first.",
+                        Fore.RED,
+                        Style.RESET_ALL,
+                    )
+                    return
+            elif len(home_configs) > 1:
+                log.error(
+                    "Multiple home config files found, "
+                    "please specify one with -c/--config",
+                )
+                return
+            else:
+                config_file_path = home_configs[0]
+        
+        format_single_config(config_file_path, write)

tests/cli/test_fmt.py

@@ -211,7 +211,7 @@ def test_format_file_no_write(
             yaml.dump(original_config, f)
 
         with caplog.at_level(logging.INFO):
-            format_config_file(str(config_file), write=False)
+            format_config_file(str(config_file), write=False, format_all=False)
 
         # Check that file was not modified
         with config_file.open(encoding="utf-8") as f:
@@ -243,7 +243,7 @@ def test_format_file_with_write(
             yaml.dump(original_config, f)
 
         with caplog.at_level(logging.INFO):
-            format_config_file(str(config_file), write=True)
+            format_config_file(str(config_file), write=True, format_all=False)
 
         # Check that file was modified
         with config_file.open(encoding="utf-8") as f:
@@ -279,7 +279,7 @@ def test_already_formatted(
             yaml.dump(config, f)
 
         with caplog.at_level(logging.INFO):
-            format_config_file(str(config_file), write=False)
+            format_config_file(str(config_file), write=False, format_all=False)
 
         assert "already formatted correctly" in caplog.text
 
@@ -320,7 +320,7 @@ def test_no_config_found(
         monkeypatch.chdir(tmp_path)
 
         with caplog.at_level(logging.ERROR):
-            format_config_file(None, write=False)
+            format_config_file(None, write=False, format_all=False)
 
         assert "No configuration file found" in caplog.text
 
@@ -345,9 +345,81 @@ def test_detailed_change_reporting(
         config_file.write_text(yaml_content, encoding="utf-8")
 
         with caplog.at_level(logging.INFO):
-            format_config_file(str(config_file), write=False)
+            format_config_file(str(config_file), write=False, format_all=False)
 
         # Check detailed change reporting
         assert "3 repositories from compact to verbose format" in caplog.text
         assert "2 repositories from 'url' to 'repo' key" in caplog.text
         assert "Directories will be sorted alphabetically" in caplog.text
+
+    def test_format_all_configs(
+        self,
+        tmp_path: pathlib.Path,
+        caplog: LogCaptureFixture,
+        monkeypatch: pytest.MonkeyPatch,
+    ) -> None:
+        """Test formatting all discovered config files."""
+        # Create test config directory structure
+        config_dir = tmp_path / ".config" / "vcspull"
+        config_dir.mkdir(parents=True)
+        
+        # Create home config (already formatted correctly)
+        home_config = tmp_path / ".vcspull.yaml"
+        home_config.write_text(
+            yaml.dump({"~/projects/": {"repo1": {"repo": "url1"}}}),
+            encoding="utf-8",
+        )
+        
+        # Create config in config directory (needs sorting)
+        config1 = config_dir / "work.yaml"
+        config1_content = """~/work/:
+  repo2: url2
+  repo1: url1
+"""
+        config1.write_text(config1_content, encoding="utf-8")
+        
+        # Create local config
+        local_config = tmp_path / "project" / ".vcspull.yaml"
+        local_config.parent.mkdir()
+        local_config.write_text(
+            yaml.dump({"./": {"repo3": {"url": "url3"}}}),
+            encoding="utf-8",
+        )
+        
+        # Mock find functions to return our test configs
+        def mock_find_config_files(include_home: bool = False) -> list[pathlib.Path]:
+            files = [config1]
+            if include_home:
+                files.insert(0, home_config)
+            return files
+        
+        def mock_find_home_config_files(filetype: list[str] | None = None) -> list[pathlib.Path]:
+            return [home_config]
+        
+        # Change to project directory
+        monkeypatch.chdir(local_config.parent)
+        monkeypatch.setattr(
+            "vcspull.cli.fmt.find_config_files",
+            mock_find_config_files,
+        )
+        monkeypatch.setattr(
+            "vcspull.cli.fmt.find_home_config_files",
+            mock_find_home_config_files,
+        )
+        
+        with caplog.at_level(logging.INFO):
+            format_config_file(None, write=False, format_all=True)
+        
+        # Check that all configs were found
+        assert "Found 3 configuration files to format" in caplog.text
+        assert str(home_config) in caplog.text
+        assert str(config1) in caplog.text
+        assert str(local_config) in caplog.text
+        
+        # Check processing messages
+        assert "already formatted correctly" in caplog.text  # home_config
+        assert "3 formatting issues" in caplog.text  # config1 has 2 compact + needs sorting
+        assert "2 repositories from compact to verbose format" in caplog.text  # config1
+        assert "Repositories in ~/work/ will be sorted" in caplog.text  # config1
+        assert "1 repository from 'url' to 'repo' key" in caplog.text  # local_config
+        assert "All 3 configuration files processed successfully" in caplog.text