import argparse
from collections.abc import Sequence
from pathlib import Path


def parse_args(args: Sequence[str] | None = None) -> argparse.Namespace:
    parser = argparse.ArgumentParser(description="Run the multi-agent SDLC workflow.")

    workflow_source = parser.add_mutually_exclusive_group(required=True)
    workflow_source.add_argument(
        "--resume",
        metavar="THREAD_ID",
        help="Resume the workflow identified by THREAD_ID.",
    )
    workflow_source.add_argument(
        "--project-description",
        type=Path,
        metavar="MARKDOWN_FILE",
        help="Start a new workflow using the selected Markdown description.",
    )

    parser.add_argument(
        "--checkpoint-id",
        metavar="CHECKPOINT_ID",
        default=None,
        help=("Optional checkpoint ID to resume from within the workflow thread."),
    )

    parser.add_argument(
        "--auto-approve-plan",
        action="store_true",
        help="Automatically approve plan reviews.",
    )

    parsed_args = parser.parse_args(args)

    if parsed_args.checkpoint_id is not None and parsed_args.resume is None:
        parser.error("--checkpoint-id can only be used with --resume")

    return parsed_args