Add 'add' and 'add-from-fs' CLI commands

This commit adds two new CLI commands to vcspull:

1. 'add' - Adds a single repository to the configuration
   - Handles different input formats (name=url, url only)
   - Supports custom base_dir_key and target_path options
   - Automatically extracts repo names from URLs when needed

2. 'add-from-fs' - Scans a directory for git repositories and adds them to the configuration
   - Supports recursive scanning with --recursive flag
   - Can use a custom base directory key with --base-dir-key
   - Provides interactive confirmation (can be bypassed with --yes)
   - Organizes nested repositories under appropriate base keys

Both commands include thorough test coverage and maintain project code style.

Author: tony

src/vcspull/cli/__init__.py

@@ -13,6 +13,8 @@
 from vcspull.__about__ import __version__
 from vcspull.log import setup_logger
 
+from .add import add_repo, create_add_subparser
+from .add_from_fs import add_from_filesystem, create_add_from_fs_subparser
 from .sync import create_sync_subparser, sync
 
 log = logging.getLogger(__name__)
@@ -41,9 +43,28 @@ def create_parser(
 def create_parser(return_subparsers: t.Literal[False]) -> argparse.ArgumentParser: ...
 
 
+@overload
+def create_parser(
+    return_subparsers: t.Literal[True], get_all_subparsers: t.Literal[True]
+) -> tuple[
+    argparse.ArgumentParser,
+    argparse._SubParsersAction[argparse.ArgumentParser],
+    dict[str, argparse.ArgumentParser],
+]: ...
+
+
 def create_parser(
     return_subparsers: bool = False,
-) -> argparse.ArgumentParser | tuple[argparse.ArgumentParser, t.Any]:
+    get_all_subparsers: bool = False,
+) -> (
+    argparse.ArgumentParser
+    | tuple[argparse.ArgumentParser, t.Any]
+    | tuple[
+        argparse.ArgumentParser,
+        argparse._SubParsersAction[argparse.ArgumentParser],
+        dict[str, argparse.ArgumentParser],
+    ]
+):
     """Create CLI argument parser for vcspull."""
     parser = argparse.ArgumentParser(
         prog="vcspull",
@@ -73,14 +94,44 @@ def create_parser(
     )
     create_sync_subparser(sync_parser)
 
+    add_parser = subparsers.add_parser(
+        "add",
+        help="add a new repository to the configuration",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        description="Adds a new repository to the vcspull configuration file.",
+    )
+    create_add_subparser(add_parser)
+
+    add_from_fs_parser = subparsers.add_parser(
+        "add-from-fs",
+        help="scan a directory for git repositories and add them to the configuration",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        description=(
+            "Scans a directory for git repositories and adds them "
+            "to the vcspull configuration file."
+        ),
+    )
+    create_add_from_fs_subparser(add_from_fs_parser)
+
+    all_subparsers_dict = {
+        "sync": sync_parser,
+        "add": add_parser,
+        "add-from-fs": add_from_fs_parser,
+    }
+
+    if get_all_subparsers:
+        return parser, subparsers, all_subparsers_dict
+
     if return_subparsers:
         return parser, sync_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_action, all_parsers = create_parser(
+        return_subparsers=True, get_all_subparsers=True
+    )
     args = parser.parse_args(_args)
 
     setup_logger(log=log, level=args.log_level.upper())
@@ -89,9 +140,42 @@ def cli(_args: list[str] | None = None) -> None:
         parser.print_help()
         return
     if args.subparser_name == "sync":
+        sync_parser = all_parsers["sync"]
+        # Extract parameters from args, providing defaults for required params
+        repo_patterns = args.repo_patterns if hasattr(args, "repo_patterns") else []
+        config_path = None
+        if hasattr(args, "config") and args.config is not None:
+            from pathlib import Path
+
+            config_path = Path(args.config)
+        exit_on_error = args.exit_on_error if hasattr(args, "exit_on_error") else False
+        # Call sync with correct parameter types
         sync(
-            repo_patterns=args.repo_patterns,
-            config=args.config,
-            exit_on_error=args.exit_on_error,
+            repo_patterns=repo_patterns,
+            config=config_path,
+            exit_on_error=exit_on_error,
             parser=sync_parser,
         )
+    elif args.subparser_name == "add":
+        add_repo_kwargs = {
+            "repo_name_or_url": args.repo_name_or_url,
+            "config_file_path_str": args.config if hasattr(args, "config") else None,
+            "target_path_str": args.target_path
+            if hasattr(args, "target_path")
+            else None,
+            "base_dir_key": args.base_dir_key
+            if hasattr(args, "base_dir_key")
+            else None,
+        }
+        add_repo(**add_repo_kwargs)
+    elif args.subparser_name == "add-from-fs":
+        add_from_fs_kwargs = {
+            "scan_dir_str": args.scan_dir,
+            "config_file_path_str": args.config if hasattr(args, "config") else None,
+            "recursive": args.recursive if hasattr(args, "recursive") else False,
+            "base_dir_key_arg": args.base_dir_key
+            if hasattr(args, "base_dir_key")
+            else None,
+            "yes": args.yes if hasattr(args, "yes") else False,
+        }
+        add_from_filesystem(**add_from_fs_kwargs)

src/vcspull/cli/add.py

@@ -0,0 +1,224 @@
+"""CLI functionality for vcspull add."""
+
+from __future__ import annotations
+
+import argparse
+import logging
+import pathlib
+import typing as t
+
+import yaml
+
+from vcspull.config import expand_dir, find_home_config_files
+
+if t.TYPE_CHECKING:
+    pass
+
+log = logging.getLogger(__name__)
+
+
+def create_add_subparser(parser: argparse.ArgumentParser) -> None:
+    """Configure :py:class:`argparse.ArgumentParser` for ``vcspull add``."""
+    parser.add_argument(
+        "-c",
+        "--config",
+        dest="config",
+        metavar="file",
+        help="path to custom config file (default: .vcspull.yaml or ~/.vcspull.yaml)",
+    )
+    parser.add_argument(
+        "--target-path",
+        dest="target_path",
+        help="target checkout path (e.g., ~/code/mylib)",
+    )
+    parser.add_argument(
+        "--base-dir-key",
+        dest="base_dir_key",
+        help="base directory key in the config (e.g., ~/code/)",
+    )
+    parser.add_argument(
+        "repo_name_or_url",
+        help=(
+            "repo_name=repo_url format, or just repo_url to extract name. "
+            "Examples: flask=git+https://github.com/pallets/flask.git, "
+            "or just git+https://github.com/pallets/flask.git"
+        ),
+    )
+
+
+def extract_repo_name_and_url(repo_name_or_url: str) -> tuple[str, str]:
+    """Extract repository name and URL from various input formats.
+
+    Parameters
+    ----------
+    repo_name_or_url : str
+        Repository name and URL in one of these formats:
+        - name=url
+        - url
+
+    Returns
+    -------
+    tuple[str, str]
+        A tuple of (repo_name, repo_url)
+    """
+    if "=" in repo_name_or_url:
+        # Format: name=url
+        repo_name, repo_url = repo_name_or_url.split("=", 1)
+    else:
+        # Format: url only, extract name from URL
+        repo_url = repo_name_or_url
+        # Extract repo name from URL
+        if repo_url.endswith(".git"):
+            repo_url_path = repo_url.rstrip("/").split("/")[-1]
+            repo_name = repo_url_path.rsplit(".git", 1)[0]
+        elif ":" in repo_url and "@" in repo_url:  # SSH URL format
+            # SSH format: [email protected]:user/repo.git
+            repo_url_path = repo_url.split(":")[-1].rstrip("/")
+            if repo_url_path.endswith(".git"):
+                repo_name = repo_url_path.split("/")[-1].rsplit(".git", 1)[0]
+            else:
+                repo_name = repo_url_path.split("/")[-1]
+        else:
+            # Just use the last part of the URL as the name
+            repo_name = repo_url.rstrip("/").split("/")[-1]
+
+    return repo_name, repo_url
+
+
+def save_config_yaml(config_file_path: pathlib.Path, data: dict[t.Any, t.Any]) -> None:
+    """Save configuration data to YAML file.
+
+    Parameters
+    ----------
+    config_file_path : pathlib.Path
+        Path to config file to save
+    data : dict[t.Any, t.Any]
+        Configuration data to save
+    """
+    # Ensure directory exists
+    config_file_path.parent.mkdir(parents=True, exist_ok=True)
+
+    # Write to file
+    with config_file_path.open("w", encoding="utf-8") as f:
+        yaml.dump(data, f, default_flow_style=False, sort_keys=False)
+
+
+def add_repo(
+    repo_name_or_url: str,
+    config_file_path_str: str | None = None,
+    target_path_str: str | None = None,
+    base_dir_key: str | None = None,
+) -> None:
+    """Add a repository to the vcspull configuration.
+
+    Parameters
+    ----------
+    repo_name_or_url : str
+        Repository name and URL in format name=url or just url
+    config_file_path_str : str, optional
+        Path to config file, by default None
+    target_path_str : str, optional
+        Target checkout path, by default None
+    base_dir_key : str, optional
+        Base directory key in the config, by default None
+    """
+    repo_name, repo_url = extract_repo_name_and_url(repo_name_or_url)
+
+    # Determine config file path
+    config_file_path: pathlib.Path
+    if config_file_path_str:
+        config_file_path = pathlib.Path(config_file_path_str).expanduser().resolve()
+    else:
+        # Default to ~/.vcspull.yaml if no global --config is passed
+        home_configs = find_home_config_files(filetype=["yaml"])
+        if not home_configs:
+            # If no configs found, create .vcspull.yaml in current directory
+            config_file_path = pathlib.Path.cwd() / ".vcspull.yaml"
+            log.info(f"No config found, will create {config_file_path}")
+        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]
+
+    # Load existing config
+    raw_config: dict[str, t.Any] = {}
+    if config_file_path.exists() and config_file_path.is_file():
+        try:
+            with config_file_path.open(encoding="utf-8") as f:
+                raw_config = yaml.safe_load(f) or {}
+            if not isinstance(raw_config, dict):
+                log.error(f"Config file {config_file_path} not a valid YAML dict")
+                return
+        except Exception:
+            log.exception(f"Error loading YAML from {config_file_path}")
+            return
+    else:
+        log.info(
+            f"Config file {config_file_path} not found. A new one will be created."
+        )
+
+    # Determine the base directory key to use in the config
+    actual_base_dir_key: str
+    if base_dir_key:
+        actual_base_dir_key = base_dir_key
+    elif target_path_str:
+        # If target path is provided, use its parent directory as the base key
+        target_dir = expand_dir(pathlib.Path(target_path_str))
+        resolved_target_dir_parent = target_dir.parent
+        try:
+            # Try to make the path relative to home
+            actual_base_dir_key = (
+                "~/"
+                + str(resolved_target_dir_parent.relative_to(pathlib.Path.home()))
+                + "/"
+            )
+        except ValueError:
+            # Use absolute path if not relative to home
+            actual_base_dir_key = str(resolved_target_dir_parent) + "/"
+    else:
+        # Default to use an existing key or create a new one
+        if raw_config and raw_config.keys():
+            # Use the first key if there's an existing configuration
+            actual_base_dir_key = next(iter(raw_config))
+        else:
+            # Default to ~/code/ for a new configuration
+            actual_base_dir_key = "~/code/"
+
+    if not actual_base_dir_key.endswith("/"):  # Ensure trailing slash for consistency
+        actual_base_dir_key += "/"
+
+    log.debug(f"Using base directory key: {actual_base_dir_key}")
+
+    # Ensure the base directory key exists in the config
+    if actual_base_dir_key not in raw_config:
+        raw_config[actual_base_dir_key] = {}
+    elif not isinstance(raw_config[actual_base_dir_key], dict):
+        log.error(
+            f"Section '{actual_base_dir_key}' is not a valid dictionary. Aborting."
+        )
+        return
+
+    # Check if repo already exists under this base key
+    if repo_name in raw_config[actual_base_dir_key]:
+        log.warning(
+            f"Repository '{repo_name}' already exists under '{actual_base_dir_key}'."
+            f" Current URL: {raw_config[actual_base_dir_key][repo_name]}."
+            f" To update, remove and re-add, or edit the YAML file manually."
+        )
+        return
+
+    # Add the repository to the configuration
+    raw_config[actual_base_dir_key][repo_name] = repo_url
+
+    try:
+        # Save config back to file
+        save_config_yaml(config_file_path, raw_config)
+        log.info(
+            f"Added '{repo_name}' ({repo_url}) to {config_file_path}"
+            f" in '{actual_base_dir_key}'."
+        )
+    except Exception:
+        log.exception(f"Error saving config to {config_file_path}")