blob: 487a35f405115a5ef46d1ae516a5c8f807499138 [file]
#!/usr/bin/env python3
"""Manage native GitHub pull request stacks via the GitHub REST API.
Usage:
.agents/scripts/gh_pr_stack.py create <pr1> <pr2> [<prN>...] [--repo <owner/name>]
.agents/scripts/gh_pr_stack.py add <stack_number> <pr1> [<prN>...] [--repo <owner/name>]
.agents/scripts/gh_pr_stack.py unstack <stack_number> <pr1> [<prN>...] [--repo <owner/name>]
.agents/scripts/gh_pr_stack.py show <stack_number> [--repo <owner/name>]
"""
from __future__ import annotations
import argparse
import json
import re
import subprocess
import sys
from collections.abc import Sequence
_DEFAULT_REPO = "bazel-contrib/rules_python"
_ACCEPT_HEADER = "Accept: application/vnd.github+json"
_REPO_SLUG_RE = re.compile(r"^[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+\Z")
def build_parser() -> argparse.ArgumentParser:
"""Builds the CLI argument parser.
Returns:
Configured `argparse.ArgumentParser` for `gh_pr_stack`.
"""
parser = argparse.ArgumentParser(
description="Manage native GitHub pull request stacks."
)
subparsers = parser.add_subparsers(dest="command", required=True)
create_parser = subparsers.add_parser(
"create", help="Create a new stack with two or more PR numbers"
)
create_parser.add_argument(
"prs", type=int, nargs="+", help="PR numbers to include in the stack"
)
create_parser.add_argument("--repo", default=_DEFAULT_REPO, help="Owner/repo slug")
add_parser = subparsers.add_parser(
"add", help="Add one or more PR numbers to an existing stack"
)
add_parser.add_argument("stack_number", type=int, help="Stack number")
add_parser.add_argument("prs", type=int, nargs="+", help="PR numbers to add")
add_parser.add_argument("--repo", default=_DEFAULT_REPO, help="Owner/repo slug")
unstack_parser = subparsers.add_parser(
"unstack", help="Remove one or more PR numbers from an existing stack"
)
unstack_parser.add_argument("stack_number", type=int, help="Stack number")
unstack_parser.add_argument("prs", type=int, nargs="+", help="PR numbers to remove")
unstack_parser.add_argument("--repo", default=_DEFAULT_REPO, help="Owner/repo slug")
show_parser = subparsers.add_parser("show", help="Display an existing stack")
show_parser.add_argument("stack_number", type=int, help="Stack number")
show_parser.add_argument("--repo", default=_DEFAULT_REPO, help="Owner/repo slug")
return parser
def validate_repo_slug(repo: str) -> str:
"""Validates an `owner/name` repository slug fail-closed.
Args:
repo: Repository slug in `owner/name` format.
Returns:
The validated `owner/name` slug.
"""
if not _REPO_SLUG_RE.match(repo):
raise ValueError(f"Invalid repository slug: {repo!r}")
owner, name = repo.split("/", 1)
if (
owner in {".", ".."}
or name in {".", ".."}
or owner.startswith("-")
or name.startswith("-")
):
raise ValueError(f"Invalid repository slug: {repo!r}")
return repo
def run_gh_api(args: Sequence[str]) -> dict:
"""Runs `gh api` with the given arguments and parses the JSON response.
Args:
args: Arguments forwarded to `gh api` after the `Accept` header.
Returns:
Parsed JSON object returned by the GitHub REST API.
"""
result = subprocess.run(
["gh", "api", "-H", _ACCEPT_HEADER, *args],
capture_output=True,
text=True,
check=True,
)
return json.loads(result.stdout or "{}")
def create_stack(repo: str, pull_requests: Sequence[int]) -> dict:
"""Creates a new GitHub PR stack containing `pull_requests`.
Args:
repo: Repository slug in `owner/name` format.
pull_requests: Pull request numbers (at least two) in stack order.
Returns:
Created stack metadata dict from GitHub REST API.
"""
if len(pull_requests) < 2:
raise ValueError("Creating a stack requires at least 2 pull request numbers")
slug = validate_repo_slug(repo)
fields = [f"-F=pull_requests[]={pr}" for pr in pull_requests]
return run_gh_api(["-X", "POST", f"repos/{slug}/stacks", *fields])
def add_to_stack(repo: str, stack_number: int, pull_requests: Sequence[int]) -> dict:
"""Adds `pull_requests` to an existing GitHub PR stack.
Args:
repo: Repository slug in `owner/name` format.
stack_number: Existing GitHub stack number.
pull_requests: Pull request numbers to append to the stack.
Returns:
Updated stack metadata dict from GitHub REST API.
"""
slug = validate_repo_slug(repo)
fields = [f"-F=pull_requests[]={pr}" for pr in pull_requests]
return run_gh_api(
["-X", "POST", f"repos/{slug}/stacks/{stack_number}/add", *fields]
)
def unstack_prs(repo: str, stack_number: int, pull_requests: Sequence[int]) -> dict:
"""Removes `pull_requests` from an existing GitHub PR stack.
Args:
repo: Repository slug in `owner/name` format.
stack_number: Existing GitHub stack number.
pull_requests: Pull request numbers to remove from the stack.
Returns:
Updated stack metadata dict from GitHub REST API.
"""
slug = validate_repo_slug(repo)
fields = [f"-F=pull_requests[]={pr}" for pr in pull_requests]
return run_gh_api(
["-X", "POST", f"repos/{slug}/stacks/{stack_number}/unstack", *fields]
)
def show_stack(repo: str, stack_number: int) -> dict:
"""Fetches metadata and pull request membership for a GitHub PR stack.
Args:
repo: Repository slug in `owner/name` format.
stack_number: Existing GitHub stack number.
Returns:
Stack metadata dict from GitHub REST API.
"""
slug = validate_repo_slug(repo)
return run_gh_api([f"repos/{slug}/stacks/{stack_number}"])
def format_stack(data: dict) -> str:
"""Formats stack JSON data as a human-readable summary.
Args:
data: Stack metadata dict returned by the GitHub `/stacks` API.
Returns:
Multi-line summary string listing the stack header and each PR.
"""
lines = [f"stack #{data['number']} base={data['base']['ref']} open={data['open']}"]
for pr in data.get("pull_requests", []):
lines.append(
f" #{pr['number']} {pr['head']['ref']} -> {pr['base']['ref']} "
f"draft={pr['draft']} state={pr['state']}"
)
return "\n".join(lines)
def main(argv: Sequence[str] | None = None) -> int:
"""CLI entrypoint.
Args:
argv: Command-line arguments (excluding `sys.argv[0]`), or `None` to use
`sys.argv[1:]`.
Returns:
Process exit code (`0` on success).
"""
args = build_parser().parse_args(argv)
if args.command == "create":
data = create_stack(args.repo, args.prs)
elif args.command == "add":
data = add_to_stack(args.repo, args.stack_number, args.prs)
elif args.command == "unstack":
data = unstack_prs(args.repo, args.stack_number, args.prs)
elif args.command == "show":
data = show_stack(args.repo, args.stack_number)
else:
raise ValueError(f"Unsupported command: {args.command!r}")
print(format_stack(data))
return 0
if __name__ == "__main__":
sys.exit(main())