git-worktree-wrapper 0.1.0__py3-none-any.whl

gww/cli/context.py

@@ -0,0 +1,382 @@
+"""Shared CLI command context: tag parsing, config loading, source resolution.
+
+This module collects the boilerplate that every command used to inline:
+
+* :class:`CommandContext` — small dataclass carrying the per-invocation state
+  (``verbose``, ``quiet``, ``tags``) plus command-specific fields (URI,
+  branch, …) that was previously pulled off ``argparse.Namespace`` with
+  ``getattr`` calls.
+* :class:`CommandExit` — control-flow exception used by ``…_or_exit``
+  helpers to abort a command with a specific exit code.
+* :func:`exit_on_error` — decorator that turns :class:`CommandExit` raised
+  inside a command into a printed error + return-code, preserving the
+  contract that ``run_<command>(ctx) -> int``.
+* :func:`parse_tags` — turn a list of ``"key=value"`` strings into a dict.
+* :func:`parse_uri_or_exit` — parse and validate a repository URI.
+* :func:`load_config_or_exit` — load + validate the gww config, raising
+  :class:`CommandExit(2, ...)` on any failure so callers do not have to repeat
+  the tri-except pattern.
+* :func:`resolve_source_repo_or_exit` — detect the current repo, walk from a
+  worktree back to its source, and return ``(source_path, remote_uri)``. Raises
+  :class:`CommandExit(1, ...)` on any failure so callers do not have to repeat
+  the detect-or-walk pattern.
+* :func:`resolve_source_repo` — same detect-or-walk pattern, but without the
+  remote-origin requirement. Used by commands that only need the source path
+  (e.g. ``pull``).
+* :class:`RuleFailure` / :func:`print_action_failure_summary` — shared
+  per-rule failure record and the grouped stderr summary used by
+  ``clone``/``add`` at the end of the action loop.
+
+Commands still own their own control flow. They raise :class:`CommandExit`
+when they want to bail out with a specific exit code; the ``@exit_on_error``
+decorator on the public ``run_<command>`` entry points converts that exception
+into the return code that the old ``return N`` pattern used to produce.
+"""
+
+from __future__ import annotations
+
+import argparse
+import functools
+import sys
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Callable, Optional, TypeVar
+
+from gww.actions import Action, ActionError, RuleActions
+from gww.config.loader import ConfigLoadError, ConfigNotFoundError, load_config
+from gww.config.validator import Config, ConfigValidationError, validate_config
+from gww.git.repository import (
+    GitCommandError,
+    NotGitRepositoryError,
+    detect_repository,
+    get_source_repository,
+)
+from gww.utils.uri import ParsedURI, parse_uri
+
+
+_F = TypeVar("_F", bound=Callable[..., Any])
+
+
+def exit_on_error(func: _F) -> _F:
+    """Decorator that converts :class:`CommandExit` into a return code.
+
+    The command's body can freely ``raise CommandExit(code, message)``;
+    the wrapper prints ``message`` to stderr and returns ``code``. Any
+    other exception propagates unchanged so the global handler in
+    :func:`gww.cli.main:main` (or the test framework) sees it.
+    """
+
+    @functools.wraps(func)
+    def wrapper(*args: Any, **kwargs: Any) -> int:
+        try:
+            result = func(*args, **kwargs)
+        except CommandExit as e:
+            if e.message:
+                print(e.message, file=sys.stderr)
+            return e.code
+        return int(result)
+
+    return wrapper  # type: ignore[return-value]
+
+
+class CommandExit(Exception):
+    """Raised when a command needs to terminate early with a specific exit code.
+
+    Attributes:
+        code: Exit code to return from the CLI. ``1`` for a runtime error,
+            ``2`` for a configuration error.
+        message: Human-readable error message. Written to stderr by
+            :func:`gww.cli.main:main` before the process exits.
+    """
+
+    def __init__(self, code: int, message: str = "") -> None:
+        super().__init__(message)
+        self.code = code
+        self.message = message
+
+
+def parse_tags(tag_args: Optional[list[str]]) -> dict[str, str]:
+    """Parse ``--tag key=value`` arguments into a dictionary.
+
+    Args:
+        tag_args: List of tag strings in format ``"key=value"`` or ``"key"``.
+
+    Returns:
+        Dictionary mapping tag keys to values (empty string if no value).
+    """
+    tags: dict[str, str] = {}
+    for tag_arg in tag_args or []:
+        if "=" in tag_arg:
+            key, value = tag_arg.split("=", 1)
+            tags[key] = value
+        else:
+            tags[tag_arg] = ""
+    return tags
+
+
+def parse_uri_or_exit(uri_str: str) -> ParsedURI:
+    """Parse a repository URI, raising :class:`CommandExit` on failure.
+
+    Args:
+        uri_str: Raw URI string from the command line.
+
+    Returns:
+        Validated :class:`ParsedURI` object.
+
+    Raises:
+        CommandExit: With code ``1`` if the URI is malformed.
+    """
+    try:
+        return parse_uri(uri_str)
+    except ValueError as e:
+        raise CommandExit(1, f"Error: Invalid repository URI: {e}") from e
+
+
+@dataclass
+class CommandContext:
+    """Per-invocation context shared by all CLI commands.
+
+    Replaces the ``getattr(args, "verbose", 0)`` / ``getattr(args, "quiet", False)``
+    pattern with a typed container. Built once from the parsed
+    :class:`argparse.Namespace` and threaded into helpers and commands.
+
+    Command-specific fields (``uri``, ``branch``, ``branch_or_path``, …) are
+    optional and only populated for the commands that need them.
+
+    Attributes:
+        verbose: Verbosity level (``-v`` count).
+        quiet: Whether to suppress non-error output (``-q``).
+        tags: Tag key-value pairs from ``--tag`` options.
+        uri: Source URI string (clone command).
+        branch: Branch name (add command).
+        branch_or_path: Branch name or worktree path (remove command).
+        create_branch: Whether to create the branch if missing (add command).
+        force: Whether to force the operation past safety checks.
+        old_repos: Source directories to scan for migration (migrate command).
+        dry_run: Whether to only report what would happen (migrate command).
+        inplace: Whether to move in place instead of copying (migrate command).
+        init_command: ``"config"`` or ``"shell"`` for ``gww init``.
+        shell: Shell name for ``gww init shell``.
+    """
+
+    verbose: int = 0
+    quiet: bool = False
+    tags: dict[str, str] = field(default_factory=dict)
+    uri: Optional[str] = None
+    branch: Optional[str] = None
+    branch_or_path: Optional[str] = None
+    create_branch: bool = False
+    force: bool = False
+    old_repos: list[str] = field(default_factory=list)
+    dry_run: bool = False
+    inplace: bool = False
+    init_command: Optional[str] = None
+    shell: Optional[str] = None
+
+    @classmethod
+    def from_args(cls, args: argparse.Namespace) -> CommandContext:
+        """Build a :class:`CommandContext` from parsed argparse args.
+
+        Args:
+            args: Parsed command-line arguments.
+
+        Returns:
+            Populated context.
+        """
+        old_repos_raw = getattr(args, "old_repos", None) or []
+        if isinstance(old_repos_raw, str):
+            old_repos = [old_repos_raw]
+        else:
+            old_repos = list(old_repos_raw)
+        return cls(
+            verbose=getattr(args, "verbose", 0),
+            quiet=getattr(args, "quiet", False),
+            tags=parse_tags(getattr(args, "tag", None)),
+            uri=getattr(args, "uri", None),
+            branch=getattr(args, "branch", None),
+            branch_or_path=getattr(args, "branch_or_path", None),
+            create_branch=getattr(args, "create_branch", False),
+            force=getattr(args, "force", False),
+            old_repos=old_repos,
+            dry_run=getattr(args, "dry_run", False),
+            inplace=getattr(args, "inplace", False),
+            init_command=getattr(args, "init_command", None),
+            shell=getattr(args, "shell", None),
+        )
+
+    def say(self, message: str) -> None:
+        """Print a status message unless quiet mode is set.
+
+        Args:
+            message: Message to write to stdout.
+        """
+        if not self.quiet:
+            print(message)
+
+    def verbose_msg(self, message: str) -> None:
+        """Print a verbose status message.
+
+        Args:
+            message: Message to write to stderr (only when ``verbose > 0``).
+        """
+        if self.verbose > 0 and not self.quiet:
+            print(message, file=sys.stderr)
+
+
+def load_config_or_exit() -> Config:
+    """Load and validate the gww configuration.
+
+    Returns:
+        Validated :class:`Config` object.
+
+    Raises:
+        CommandExit: With code ``2`` if the config is missing, malformed, or
+            fails validation.
+    """
+    try:
+        raw_config = load_config()
+    except ConfigNotFoundError as e:
+        raise CommandExit(
+            2,
+            "Error: Config file not found. Run 'gww init config' to create one.",
+        ) from e
+    except ConfigLoadError as e:
+        raise CommandExit(2, f"Error: {e}") from e
+
+    try:
+        return validate_config(raw_config)
+    except ConfigValidationError as e:
+        raise CommandExit(2, f"Config validation error: {e}") from e
+
+
+def resolve_source_repo_or_exit(cwd: Path) -> tuple[Path, str]:
+    """Detect the repo at ``cwd`` and walk back to its source.
+
+    If ``cwd`` is inside a worktree, the source (main) repository path is
+    returned along with that source repo's remote URI. If ``cwd`` is inside a
+    source repository, that path and its remote URI are returned.
+
+    Args:
+        cwd: Directory to start the detection from.
+
+    Returns:
+        Tuple of ``(source_path, remote_uri)``.
+
+    Raises:
+        CommandExit: With code ``1`` if ``cwd`` is not in a git repository, the
+            source cannot be found, or the repo has no remote ``origin``.
+    """
+    try:
+        repo = detect_repository(cwd)
+    except NotGitRepositoryError as e:
+        raise CommandExit(1, "Error: Not in a git repository.") from e
+
+    if repo.is_worktree:
+        try:
+            source_path = get_source_repository(repo.path)
+        except (NotGitRepositoryError, GitCommandError) as e:
+            raise CommandExit(1, f"Error finding source repository: {e}") from e
+    else:
+        source_path = repo.path
+
+    if not repo.remote_uri:
+        raise CommandExit(
+            1,
+            "Error: Repository has no remote origin. "
+            "Cannot determine worktree path.",
+        )
+
+    return source_path, repo.remote_uri
+
+
+def resolve_source_repo(cwd: Path) -> Path:
+    """Detect repo at ``cwd`` and walk back to its source.
+
+    Unlike :func:`resolve_source_repo_or_exit` this helper does not require
+    a remote origin — it returns the source path regardless of remote state.
+    Used by commands that operate on the local source (e.g. ``pull``).
+
+    Args:
+        cwd: Directory to start the detection from.
+
+    Returns:
+        Path to the source repository.
+
+    Raises:
+        CommandExit: With code ``1`` if ``cwd`` is not in a git repository or
+            the source repo cannot be found.
+    """
+    try:
+        repo = detect_repository(cwd)
+    except NotGitRepositoryError as e:
+        raise CommandExit(1, "Error: Not in a git repository.") from e
+
+    if repo.is_worktree:
+        try:
+            return get_source_repository(repo.path)
+        except (NotGitRepositoryError, GitCommandError) as e:
+            raise CommandExit(1, f"Error finding source repository: {e}") from e
+    return repo.path
+
+
+@dataclass
+class RuleFailure:
+    """A single failing action in the clone/add action loop.
+
+    Pairs the failing :class:`Action` with the :class:`RuleActions` bundle it
+    came from and the :class:`ActionError` it raised. Used by
+    :func:`print_action_failure_summary` to produce the grouped stderr block,
+    and by the CLI to choose the exit code (any failure with
+    ``bundle.critical`` set → exit 1).
+
+    Attributes:
+        bundle: The rule that produced the action.
+        action: The action whose ``run()`` raised.
+        error: The exception raised by ``action.run()``.
+    """
+
+    bundle: RuleActions
+    action: Action
+    error: ActionError
+
+
+def _describe_action(action: Action) -> str:
+    """Return a short human-readable label for an action in failure messages.
+
+    Uses the action's concrete class name (e.g. ``"copy"``, ``"command"``) —
+    no need to add a method to the action classes just for diagnostics. The
+    ``"Action"`` suffix is stripped and the result lowercased, so
+    ``CopyAction`` → ``"copy"`` and ``CommandAction`` → ``"command"``.
+    """
+    name = type(action).__name__
+    if name.endswith("Action"):
+        name = name[: -len("Action")]
+    return name.lower()
+
+
+def print_action_failure_summary(failures: list[RuleFailure]) -> None:
+    """Print the grouped action-execution summary to stderr.
+
+    Lists one entry per failing action, identified by the rule's config index,
+    the rule's criticality, the failing action's type, and the error text.
+    Critical rules' loops break after the first failure, so each critical rule
+    appears at most once; non-critical rules appear once per failing action.
+    Suppressing the ``say()`` success line is the caller's responsibility — the
+    helper only renders the block.
+
+    Args:
+        failures: Failures collected by the CLI action loop, in order.
+    """
+    print(
+        f"Action execution summary: {len(failures)} failure(s):",
+        file=sys.stderr,
+    )
+    for failure in failures:
+        criticality = "critical" if failure.bundle.critical else "non-critical"
+        action_label = _describe_action(failure.action)
+        print(
+            f"  Rule {failure.bundle.index} ({criticality}, "
+            f"when: {failure.bundle.predicate}): "
+            f"failed at {action_label}: {failure.error}",
+            file=sys.stderr,
+        )

gww/cli/main.py

@@ -0,0 +1,285 @@
+"""CLI entry point and argument parser structure."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from typing import Optional, Sequence
+
+from gww import __version__
+from gww.cli.context import CommandContext, CommandExit
+
+
+def create_parser() -> argparse.ArgumentParser:
+    """Create the main argument parser with all subcommands.
+
+    The returned parser has ``init_parser`` attached as an attribute so
+    callers (notably :func:`main`) can print help for the ``init`` command
+    without re-creating the parser.
+
+    Returns:
+        Configured ArgumentParser.
+    """
+    parser = argparse.ArgumentParser(
+        prog="gww",
+        description="Git Worktree Wrapper - manage git worktrees with configurable paths",
+        epilog="Run 'gww <command> --help' for more information on a specific command.",
+    )
+
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"%(prog)s {__version__}",
+    )
+
+    parser.add_argument(
+        "-v", "--verbose",
+        action="count",
+        default=0,
+        help="Increase verbosity (can be repeated)",
+    )
+
+    parser.add_argument(
+        "-q", "--quiet",
+        action="store_true",
+        help="Suppress non-error output",
+    )
+
+    parser.add_argument(
+        "-t", "--tag",
+        action="append",
+        default=[],
+        help="Tag in format key=value or just key (can be specified multiple times)",
+        metavar="TAG",
+    )
+
+    # Create subparsers for commands
+    subparsers = parser.add_subparsers(
+        dest="command",
+        title="commands",
+        metavar="<command>",
+    )
+
+    # clone command
+    clone_parser = subparsers.add_parser(
+        "clone",
+        help="Clone a repository to configured location",
+        description="Clone a git repository to the location determined by configuration rules.",
+    )
+    clone_parser.add_argument(
+        "uri",
+        help="Git repository URI (HTTP, HTTPS, SSH, or file://)",
+    )
+    clone_parser.add_argument(
+        "-t", "--tag",
+        action="append",
+        default=[],
+        help="Tag in format key=value or just key (can be specified multiple times)",
+        metavar="TAG",
+    )
+
+    # add command
+    add_parser = subparsers.add_parser(
+        "add",
+        help="Add a worktree for a branch",
+        description="Add a worktree for the specified branch.",
+    )
+    add_parser.add_argument(
+        "branch",
+        help="Branch name to checkout in worktree",
+    )
+    add_parser.add_argument(
+        "-c", "--create-branch",
+        action="store_true",
+        help="Create branch from current commit if it doesn't exist",
+    )
+    add_parser.add_argument(
+        "-t", "--tag",
+        action="append",
+        default=[],
+        help="Tag in format key=value or just key (can be specified multiple times)",
+        metavar="TAG",
+    )
+
+    # remove command
+    remove_parser = subparsers.add_parser(
+        "remove",
+        help="Remove a worktree",
+        description="Remove a worktree by branch name or path.",
+    )
+    remove_parser.add_argument(
+        "branch_or_path",
+        help="Branch name or absolute path to worktree",
+    )
+    remove_parser.add_argument(
+        "-f", "--force",
+        action="store_true",
+        help="Force removal even if worktree has uncommitted changes",
+    )
+    remove_parser.add_argument(
+        "-t", "--tag",
+        action="append",
+        default=[],
+        help="Tag in format key=value or just key (can be specified multiple times)",
+        metavar="TAG",
+    )
+
+    # pull command
+    pull_parser = subparsers.add_parser(
+        "pull",
+        help="Update source repository",
+        description="Pull changes from remote in the source repository.",
+    )
+
+    # migrate command
+    migrate_parser = subparsers.add_parser(
+        "migrate",
+        help="Migrate repositories to new locations",
+        description="Scan directory for repositories and migrate them based on current configuration.",
+    )
+    migrate_parser.add_argument(
+        "old_repos",
+        nargs="+",
+        help="Path(s) to directory(ies) containing old repositories",
+    )
+    migrate_parser.add_argument(
+        "-n", "--dry-run",
+        action="store_true",
+        help="Show what would be migrated without making changes",
+    )
+    migrate_group = migrate_parser.add_mutually_exclusive_group()
+    migrate_group.add_argument(
+        "--copy",
+        action="store_true",
+        help="Copy repositories to new locations (default)",
+    )
+    migrate_group.add_argument(
+        "--inplace",
+        action="store_true",
+        help="Move repositories in place and clean empty source folders",
+    )
+
+    # init command (with subcommands)
+    init_parser = subparsers.add_parser(
+        "init",
+        help="Initialize config or shell completion",
+        description="Create default configuration file or install shell completion.",
+    )
+
+    init_subparsers = init_parser.add_subparsers(
+        dest="init_command",
+        title="init commands",
+        metavar="<init_command>",
+    )
+
+    # init config
+    init_config_parser = init_subparsers.add_parser(
+        "config",
+        help="Create default configuration file",
+        description="Create a default configuration file with examples and documentation.",
+    )
+
+    # init shell
+    init_shell_parser = init_subparsers.add_parser(
+        "shell",
+        help="Install shell completion",
+        description="Generate and install shell autocompletion script.",
+    )
+    init_shell_parser.add_argument(
+        "shell",
+        choices=["bash", "zsh", "fish"],
+        help="Shell to install completion for",
+    )
+
+    parser.init_parser = init_parser  # type: ignore[attr-defined]
+    return parser
+
+
+def main(argv: Optional[Sequence[str]] = None) -> int:
+    """Main entry point for gww CLI.
+
+    Args:
+        argv: Command line arguments (defaults to sys.argv[1:]).
+
+    Returns:
+        Exit code (0 for success, 1 for error, 2 for config error).
+    """
+    parser = create_parser()
+    args = parser.parse_args(argv)
+
+    if args.command is None:
+        parser.print_help()
+        return 0
+
+    # Remind the user if their installed shell alias predates the current
+    # source. Skipped for `gww init shell` since that's the command that
+    # rewrites the alias file (no point nagging mid-regeneration).
+    if not (args.command == "init" and getattr(args, "init_command", None) == "shell"):
+        from gww.cli.commands.init import detect_user_shell, warn_if_alias_is_stale
+
+        shell = detect_user_shell()
+        if shell is not None:
+            warn_if_alias_is_stale(shell)
+
+    ctx = CommandContext.from_args(args)
+
+    # Import and run command handlers
+    try:
+        if args.command == "clone":
+            from gww.cli.commands.clone import run_clone
+            return run_clone(ctx)
+
+        elif args.command == "add":
+            from gww.cli.commands.add import run_add
+            return run_add(ctx)
+
+        elif args.command == "remove":
+            from gww.cli.commands.remove import run_remove
+            return run_remove(ctx)
+
+        elif args.command == "pull":
+            from gww.cli.commands.pull import run_pull
+            return run_pull(ctx)
+
+        elif args.command == "migrate":
+            from gww.cli.commands.migrate import run_migrate
+            return run_migrate(ctx)
+
+        elif args.command == "init":
+            if args.init_command is None:
+                parser.init_parser.print_help()  # type: ignore[attr-defined]
+                return 0
+
+            if args.init_command == "config":
+                from gww.cli.commands.init import run_init_config
+                return run_init_config(ctx)
+
+            elif args.init_command == "shell":
+                from gww.cli.commands.init import run_init_shell
+                return run_init_shell(ctx)
+
+        else:
+            parser.print_help()
+            return 1
+
+    except CommandExit as e:
+        if e.message:
+            print(e.message, file=sys.stderr)
+        return e.code
+
+    except KeyboardInterrupt:
+        print("\nOperation cancelled.", file=sys.stderr)
+        return 130
+
+    except Exception as e:
+        print(f"Error: {e}", file=sys.stderr)
+        if ctx.verbose > 0:
+            import traceback
+            traceback.print_exc()
+        return 1
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

gww/config/__init__.py

@@ -0,0 +1 @@
+"""Configuration loading and management."""