#!/usr/bin/env python3
"""A small CLI that greets a user."""

import argparse
from collections.abc import Sequence


def build_parser() -> argparse.ArgumentParser:
    """Create the command-line argument parser."""
    parser = argparse.ArgumentParser(description="Print a friendly greeting.")
    parser.add_argument("name", help="name of the person to greet")
    parser.add_argument(
        "-n",
        "--count",
        type=int,
        default=1,
        help="number of greetings to print (default: 1)",
    )
    parser.add_argument(
        "--uppercase",
        action="store_true",
        help="print the greeting in uppercase",
    )
    return parser


def positive_count(value: int) -> int:
    """Validate that a greeting count is positive."""
    if value < 1:
        raise ValueError("count must be at least 1")
    return value


def format_greetings(name: str, count: int, uppercase: bool = False) -> str:
    """Return one or more formatted greetings."""
    greeting = f"Hello, {name}!"
    if uppercase:
        greeting = greeting.upper()
    return "\n".join(greeting for _ in range(positive_count(count)))


def main(argv: Sequence[str] | None = None) -> int:
    """Run the command-line interface."""
    args = build_parser().parse_args(argv)

    try:
        output = format_greetings(args.name, args.count, args.uppercase)
    except ValueError as error:
        build_parser().error(str(error))

    print(output)
    return 0


def _run_tests() -> None:
    """Run a couple of lightweight tests."""
    assert format_greetings("Ada", 1) == "Hello, Ada!"
    assert format_greetings("Lin", 2, uppercase=True) == (
        "HELLO, LIN!\nHELLO, LIN!"
    )


if __name__ == "__main__":
    raise SystemExit(main())