Emit UTC timestamp + full git SHA for GH issue/PR provenance stamps

stamp-provenance.py

#!/usr/bin/env -S uv run --script
# /// script
# requires-python = ">=3.13"
# dependencies = []
# ///
"""Emit UTC timestamp + full git SHA for GH issue/PR provenance stamps."""

from __future__ import annotations

import argparse
import json
import subprocess
import sys
from datetime import UTC
from datetime import datetime

_HELP = """\
Print a UTC timestamp and full git SHA for appending to GitHub issues or PRs.

Errors go to stderr; exit 1 if the ref cannot be resolved.

Examples:
  # Markdown against origin/main (default):
  #   Stamped `<full-sha>` at `<iso8601>`.
  scripts/stamp-provenance.py

  # Same shape, but for the current branch tip
  scripts/stamp-provenance.py -b @

  # JSON: {"git_sha":"<full-sha>","timestamp":"<iso8601>"}
  scripts/stamp-provenance.py --format=json
  scripts/stamp-provenance.py -b @ --format=json

  # Append a stamp to an issue comment
  gh issue comment 123 --body "$(scripts/stamp-provenance.py -b @)"
"""


def resolve_ref(base: str) -> str:
    return "HEAD" if base == "@" else base


def git_sha(ref: str) -> str:
    result = subprocess.run(  # noqa: S603
        ["git", "rev-parse", "--verify", f"{ref}^{{commit}}"],  # noqa: S607
        check=False,
        capture_output=True,
        text=True,
    )
    if result.returncode != 0:
        detail = (result.stderr or result.stdout).strip() or f"unknown ref: {ref}"
        sys.stderr.write(f"stamp-provenance: {detail}\n")
        sys.exit(1)
    return result.stdout.strip()


def utc_now_iso() -> str:
    return datetime.now(UTC).strftime("%Y-%m-%dT%H:%M:%SZ")


def main() -> None:
    parser = argparse.ArgumentParser(
        description=_HELP,
        formatter_class=argparse.RawDescriptionHelpFormatter,
    )
    parser.add_argument(
        "-b",
        "--base",
        default="origin/main",
        metavar="REF",
        help="git ref whose full SHA to stamp (default: origin/main; @ = HEAD)",
    )
    parser.add_argument(
        "--format",
        choices=("markdown-human", "json"),
        default="markdown-human",
        metavar="FMT",
        help=("markdown-human (default) or json — see Examples for the shapes"),
    )
    args = parser.parse_args()

    sha = git_sha(resolve_ref(args.base))
    timestamp = utc_now_iso()

    if args.format == "json":
        payload = json.dumps(
            {"git_sha": sha, "timestamp": timestamp},
            separators=(",", ":"),
        )
        sys.stdout.write(f"{payload}\n")
    else:
        sys.stdout.write(f"Stamped `{sha}` at `{timestamp}`.\n")


if __name__ == "__main__":
    main()