cli(feat[commands]): add import/fmt subcommands and streaming fixes

why:
- expose configuration management (import, import --scan, fmt) through the main CLI
- keep user-facing output visible after the logging refactor
- ensure default config readers use UTF-8 consistently

what:
- wire import/import --scan/fmt subcommands into `vcspull` CLI entry and parser
- implement `cli/import_.py`, `cli/fmt.py` plus extensive tests
- centralize config saves via `save_config_yaml` and open configs as UTF-8
- refactor `setup_logger` to replace NullHandler with stdout stream and add
  regression test for CLI output
- expand logging test suite to cover formatter and propagation behavior

This keeps the subject succinct while the bullets break down the “why/what” of
the large diff. Adjust component prefixes as needed if you prefer more
granularity (e.g., separate commits per concern), but this structure documents
all the key changes in one place.

Author: tony

src/vcspull/_internal/config_reader.py

@@ -104,7 +104,7 @@ def _from_file(cls, path: pathlib.Path) -> dict[str, t.Any]:
         {'session_name': 'my session'}
         """
         assert isinstance(path, pathlib.Path)
-        content = path.open().read()
+        content = path.open(encoding="utf-8").read()
 
         if path.suffix in {".yaml", ".yml"}:
             fmt: FormatLiteral = "yaml"

src/vcspull/cli/__init__.py

@@ -4,6 +4,7 @@
 
 import argparse
 import logging
+import pathlib
 import textwrap
 import typing as t
 from typing import overload
@@ -13,6 +14,12 @@
 from vcspull.__about__ import __version__
 from vcspull.log import setup_logger
 
+from ._import import (
+    create_import_subparser,
+    import_from_filesystem,
+    import_repo,
+)
+from .fmt import create_fmt_subparser, format_config_file
 from .sync import create_sync_subparser, sync
 
 log = logging.getLogger(__name__)
@@ -73,14 +80,36 @@ def create_parser(
     )
     create_sync_subparser(sync_parser)
 
+    import_parser = subparsers.add_parser(
+        "import",
+        help="import repository or scan filesystem for repositories",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        description="Import a repository to the vcspull configuration file. "
+        "Can import a single repository by name and URL, or scan a directory "
+        "to discover and import multiple repositories.",
+    )
+    create_import_subparser(import_parser)
+
+    fmt_parser = subparsers.add_parser(
+        "fmt",
+        help="format vcspull configuration files",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        description="Format vcspull configuration files for consistency. "
+        "Normalizes compact format to verbose format, standardizes on 'repo' key, "
+        "and sorts directories and repositories alphabetically.",
+    )
+    create_fmt_subparser(fmt_parser)
+
     if return_subparsers:
-        return parser, sync_parser
+        # Return all parsers needed by cli() function
+        return parser, (sync_parser, import_parser, fmt_parser)
     return parser
 
 
 def cli(_args: list[str] | None = None) -> None:
     """CLI entry point for vcspull."""
-    parser, sync_parser = create_parser(return_subparsers=True)
+    parser, subparsers = create_parser(return_subparsers=True)
+    sync_parser, _import_parser, _fmt_parser = subparsers
     args = parser.parse_args(_args)
 
     setup_logger(log=log, level=args.log_level.upper())
@@ -91,7 +120,33 @@ def cli(_args: list[str] | None = None) -> None:
     if args.subparser_name == "sync":
         sync(
             repo_patterns=args.repo_patterns,
-            config=args.config,
+            config=pathlib.Path(args.config) if args.config else None,
             exit_on_error=args.exit_on_error,
             parser=sync_parser,
         )
+    elif args.subparser_name == "import":
+        # Unified import command
+        if args.scan_dir:
+            # Filesystem scan mode
+            import_from_filesystem(
+                scan_dir_str=args.scan_dir,
+                config_file_path_str=args.config,
+                recursive=args.recursive,
+                base_dir_key_arg=args.base_dir_key,
+                yes=args.yes,
+            )
+        elif args.name and args.url:
+            # Manual import mode
+            import_repo(
+                name=args.name,
+                url=args.url,
+                config_file_path_str=args.config,
+                path=args.path,
+                base_dir=args.base_dir,
+            )
+        else:
+            # Error: need either name+url or --scan
+            log.error("Either provide NAME and URL, or use --scan DIR")
+            parser.exit(status=2)
+    elif args.subparser_name == "fmt":
+        format_config_file(args.config, args.write, args.all)