zithub 0.1.0__py3-none-any.whl

zithub/__init__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+__all__ = ["main"]

zithub/cli.py

@@ -0,0 +1,643 @@
+"""zh: batched `gh` PR/release actions for AI agents — PR merge preflight,
+review-thread reply/resolve, and release preflight/create, each as one call
+instead of several chained `gh`/API calls. Actions `gh` already does in a
+single call (create, close, comment, review, label, reviewer) are left to
+`gh` itself."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+import time
+
+from . import gh, versioning
+
+
+def _color(text: str, code: str) -> str:
+    if not sys.stdout.isatty():
+        return text
+    return f"\033[{code}m{text}\033[0m"
+
+
+def _green(text: str) -> str:
+    return _color(text, "32")
+
+
+def _red(text: str) -> str:
+    return _color(text, "31")
+
+
+def _yellow(text: str) -> str:
+    return _color(text, "33")
+
+
+def _dim(text: str) -> str:
+    return _color(text, "2")
+
+
+def _add_ref_arg(p: argparse.ArgumentParser) -> None:
+    p.add_argument(
+        "ref", nargs="?", help="PR number, URL, or branch (default: current branch's PR)"
+    )
+
+
+def _gh_ref_args(args: argparse.Namespace) -> list[str]:
+    return [args.ref] if args.ref else []
+
+
+# ---------------------------------------------------------------------------
+# review threads — gh has no subcommand for these at all
+
+def _print_thread(t: gh.ReviewThread) -> None:
+    status = _dim("(resolved)") if t.is_resolved else _red("(unresolved)")
+    loc = f"{t.path}:{t.line}" if t.path else ""
+    print(f"{t.id}  {loc}  {status}")
+    for c in t.comments:
+        print(f"    {c.author}  {_dim(c.created_at)}")
+        for line in c.body.splitlines():
+            print(f"      {line}")
+
+
+def cmd_threads(args: argparse.Namespace) -> int:
+    try:
+        repo = gh.repo_info()
+        pr = gh.resolve_pr(args.ref)
+        threads = gh.review_threads(repo.owner, repo.name, pr.number)
+    except gh.ZithubError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+
+    shown = threads if args.all else [t for t in threads if not t.is_resolved]
+    if args.path:
+        shown = [t for t in shown if t.path and args.path in t.path]
+
+    if not shown:
+        print("no matching review threads")
+        return 0
+    for t in shown:
+        _print_thread(t)
+        print()
+    return 0
+
+
+def cmd_reply(args: argparse.Namespace) -> int:
+    try:
+        url = gh.reply_to_thread(args.thread_id, args.body)
+        if args.resolve:
+            gh.resolve_thread(args.thread_id)
+    except gh.ZithubError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+    print(_green(f"replied: {url}"))
+    if args.resolve:
+        print(_green("resolved"))
+    return 0
+
+
+def cmd_resolve(args: argparse.Namespace) -> int:
+    try:
+        ids = list(args.thread_id)
+        if args.all:
+            repo = gh.repo_info()
+            pr = gh.resolve_pr(args.ref)
+            threads = gh.review_threads(repo.owner, repo.name, pr.number)
+            for t in threads:
+                if t.is_resolved:
+                    continue
+                if args.path and not (t.path and args.path in t.path):
+                    continue
+                ids.append(t.id)
+        if not ids:
+            print("no threads to resolve", file=sys.stderr)
+            return 1
+        for thread_id in ids:
+            ok = gh.resolve_thread(thread_id)
+            print(f"{_green('resolved') if ok else _red('failed')}  {thread_id}")
+    except gh.ZithubError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+    return 0
+
+
+def cmd_unresolve(args: argparse.Namespace) -> int:
+    try:
+        for thread_id in args.thread_id:
+            ok = gh.unresolve_thread(thread_id)
+            print(f"{_green('unresolved') if ok else _red('failed')}  {thread_id}")
+    except gh.ZithubError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+    return 0
+
+
+# ---------------------------------------------------------------------------
+# merge / ship — the real bundling: preflight checks (draft, review decision,
+# unresolved threads, CI) folded into the merge call instead of an agent
+# chaining `gh pr view` + `gh pr checks` + review-thread queries + `gh pr
+# merge` by hand
+
+_MERGE_POLL_INTERVAL_SECONDS = 15
+
+
+def _wait_for_checks(ref: str | None, timeout: int) -> gh.PullRequest:
+    """Poll the PR until no check is still pending, or `timeout` elapses."""
+    deadline = time.monotonic() + timeout
+    pr = gh.resolve_pr(ref)
+    while any(gh.is_pending(c) for c in pr.checks) and time.monotonic() < deadline:
+        pending = [c.name for c in pr.checks if gh.is_pending(c)]
+        print(_dim(f"       waiting on CI: {', '.join(pending)}"))
+        time.sleep(_MERGE_POLL_INTERVAL_SECONDS)
+        pr = gh.resolve_pr(ref)
+    return pr
+
+
+def cmd_merge(args: argparse.Namespace) -> int:
+    try:
+        pr = gh.resolve_pr(args.ref)
+    except gh.ZithubError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+
+    print(f"pr     #{pr.number} {pr.title}")
+    print(f"       {pr.url}")
+
+    if not args.force:
+        if pr.is_draft:
+            print("error: PR is a draft — mark ready or pass --force", file=sys.stderr)
+            return 1
+        if pr.review_decision == "CHANGES_REQUESTED":
+            print("error: changes requested — address review or pass --force", file=sys.stderr)
+            return 1
+
+        try:
+            repo = gh.repo_info()
+            threads = gh.review_threads(repo.owner, repo.name, pr.number)
+        except gh.ZithubError:
+            threads = []
+        unresolved = [t for t in threads if not t.is_resolved]
+        if unresolved:
+            print(
+                f"error: {len(unresolved)} unresolved review thread(s) — "
+                "resolve them, or pass --force",
+                file=sys.stderr,
+            )
+            return 1
+
+        if args.wait:
+            pr = _wait_for_checks(args.ref, args.timeout)
+        failed = [c for c in pr.checks if gh.is_failed(c)]
+        pending = [c for c in pr.checks if gh.is_pending(c)]
+        if failed:
+            names = ", ".join(c.name for c in failed)
+            print(f"error: failing check(s): {names}", file=sys.stderr)
+            return 1
+        if pending:
+            names = ", ".join(c.name for c in pending)
+            print(f"error: still pending: {names} (rerun with --wait, or pass --force)", file=sys.stderr)
+            return 1
+
+    cmd = ["gh", "pr", "merge", *_gh_ref_args(args), f"--{args.method}"]
+    if args.delete_branch:
+        cmd.append("--delete-branch")
+    if args.admin:
+        cmd.append("--admin")
+    if args.auto:
+        cmd.append("--auto")
+    if args.subject:
+        cmd += ["--subject", args.subject]
+    if args.body:
+        cmd += ["--body", args.body]
+    return gh.run_passthrough(cmd)
+
+
+def _add_merge_args(p: argparse.ArgumentParser, default_delete_branch: bool) -> None:
+    _add_ref_arg(p)
+    p.add_argument(
+        "--method",
+        choices=["squash", "merge", "rebase"],
+        default="squash",
+        help="merge strategy (default: squash)",
+    )
+    p.add_argument(
+        "--delete-branch",
+        dest="delete_branch",
+        action="store_true",
+        default=default_delete_branch,
+        help="delete the branch after merging",
+    )
+    p.add_argument(
+        "--keep-branch",
+        dest="delete_branch",
+        action="store_false",
+        help="keep the branch after merging",
+    )
+    p.add_argument("--admin", action="store_true", help="bypass branch protection as an admin")
+    p.add_argument("--auto", action="store_true", help="enable auto-merge instead of merging now")
+    p.add_argument("--subject", "-t", help="merge commit subject")
+    p.add_argument("--body", "-b", help="merge commit body")
+    p.add_argument(
+        "--force",
+        action="store_true",
+        help="skip the draft/review/unresolved-thread/CI preflight and merge immediately",
+    )
+    p.add_argument(
+        "--no-wait",
+        dest="wait",
+        action="store_false",
+        default=True,
+        help="don't poll pending checks to completion — fail immediately if any are still running",
+    )
+    p.add_argument(
+        "--timeout",
+        type=int,
+        default=1200,
+        help="max seconds to wait on pending checks (default: 1200)",
+    )
+    p.set_defaults(func=cmd_merge)
+
+
+# ---------------------------------------------------------------------------
+# release preflight / create — ports the github-release skill's preflight.py
+# (gh auth, target branch, remote sync, CI) so `release create` can gate on
+# it directly: one call that checks readiness and creates the release,
+# instead of a separate preflight script plus a hand-typed `gh release
+# create`.
+
+_CI_QUICK_ATTEMPTS = 5
+_CI_QUICK_INTERVAL_SECONDS = 1
+_CI_POLL_INTERVAL_SECONDS = 20
+_CI_MAX_ATTEMPTS = 30
+
+
+def _print_run_failures(runs: list[gh.WorkflowRun]) -> None:
+    for r in runs:
+        print(f"       {_red(r.name)}={r.conclusion}  {r.url}")
+        tail = gh.run_failure_log(r.database_id)
+        if tail:
+            print(_dim(f"       ── {r.name} (log tail) ──"))
+            for line in tail.splitlines():
+                print(f"       {_dim('|')} {line}")
+
+
+def _wait_for_release_ci(sha: str, branch: str) -> bool:
+    """True if CI passed (or no CI exists at all — proceed on judgement),
+    False if it failed or never completed. Mirrors the github-release
+    skill's preflight polling: a short grace period for the run to appear,
+    then a longer poll while anything is still in progress."""
+    runs: list[gh.WorkflowRun] = []
+    for attempt in range(_CI_MAX_ATTEMPTS):
+        runs = gh.runs_for_commit(sha)
+        if not runs:
+            if attempt >= _CI_QUICK_ATTEMPTS:
+                break
+            time.sleep(_CI_QUICK_INTERVAL_SECONDS)
+            continue
+        pending = [r for r in runs if r.status != "completed"]
+        if not pending:
+            break
+        names = ", ".join(f"{r.name}={r.status}" for r in runs)
+        print(_dim(f"       waiting on CI: {names}"))
+        time.sleep(_CI_POLL_INTERVAL_SECONDS)
+
+    if not runs:
+        latest = gh.latest_runs_for_branch(branch, limit=5)
+        failed = [r for r in latest if r.status == "completed" and r.conclusion != "success"]
+        if failed:
+            print(f"ci     {_red('no run for this commit; latest ' + branch + ' runs failed')}")
+            _print_run_failures(failed)
+            return False
+        print(_dim("ci     no run found for this commit — proceed with judgement"))
+        return True
+
+    pending = [r for r in runs if r.status != "completed"]
+    if pending:
+        names = ", ".join(f"{r.name}={r.status}" for r in pending)
+        print(f"error: CI did not complete on {sha[:12]}: {names}", file=sys.stderr)
+        return False
+
+    failed = [r for r in runs if r.conclusion != "success"]
+    if failed:
+        print(f"ci     {_red('failed')}", file=sys.stderr)
+        _print_run_failures(failed)
+        return False
+
+    names = ", ".join(r.name for r in runs)
+    print(f"ci     {_green('success')} ({names})")
+    return True
+
+
+def _release_preflight(target_arg: str | None) -> tuple[str, str, list[gh.ReleaseInfo]] | None:
+    """Runs every preflight check, printing progress as it goes. Returns
+    (target_branch, head_sha, recent_releases) on pass, None on failure (the
+    specific check that failed has already printed its own error)."""
+    try:
+        branch = gh.current_branch()
+    except gh.ZithubError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return None
+
+    try:
+        account = gh.ensure_gh_account_for_repo()
+        print(f"auth   {account}")
+    except gh.ZithubError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return None
+
+    try:
+        repo = gh.repo_info()
+    except gh.ZithubError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return None
+
+    target = target_arg or repo.default_branch
+    if branch != target:
+        override = "" if target_arg else f" or rerun with `--target {branch}`"
+        print(
+            f"error: current branch is '{branch}', but release target is "
+            f"'{target}'; check out '{target}'{override}",
+            file=sys.stderr,
+        )
+        return None
+    print(f"branch {branch}  (release target)")
+
+    try:
+        releases = gh.recent_releases()
+    except gh.ZithubError:
+        releases = []
+    if releases:
+        print("releases")
+        for r in releases:
+            kind = " (draft)" if r.is_draft else " (prerelease)" if r.is_prerelease else ""
+            print(f"       {r.tag_name}{kind}  {r.published_at}")
+
+    try:
+        dirty = gh.dirty_files()
+    except gh.ZithubError:
+        dirty = []
+    if dirty:
+        print(_yellow("local  dirty — do not release until everything is committed:"))
+        for line in dirty:
+            print(f"       {line}")
+    else:
+        print(f"local  {_green('clean')}")
+
+    try:
+        gh.fetch_all()
+        sha = gh.current_commit_sha()
+        remote_sha = gh.remote_branch_sha(target)
+    except gh.ZithubError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return None
+    if remote_sha is None:
+        print(
+            f"error: origin/{target} not found — push with `git push -u origin {target}` first",
+            file=sys.stderr,
+        )
+        return None
+    if sha != remote_sha:
+        print(
+            f"error: local HEAD ({sha[:12]}) != origin/{target} ({remote_sha[:12]}) — "
+            f"push with `git push origin {target}` or reconcile, then retry",
+            file=sys.stderr,
+        )
+        return None
+    print(f"sync   ok ({sha[:12]})")
+
+    if not _wait_for_release_ci(sha, target):
+        return None
+
+    return target, sha, releases
+
+
+def _print_commits(previous_tag: str | None) -> None:
+    try:
+        commits = gh.commits_since(previous_tag)
+    except gh.ZithubError:
+        commits = []
+    if not commits:
+        return
+    label = f"commits since {previous_tag}" if previous_tag else "commits (first release)"
+    print(f"\n{label}:")
+    for c in commits:
+        print(f"       {c}")
+
+
+def _gh_release_create_hint(tag: str, target_arg: str | None) -> str:
+    """The literal `gh release create` command to run once notes are
+    written. Points at plain `gh`, not `zh release create` — the preflight
+    that command would redo (including the CI wait) was just run right
+    here, so re-running it a moment later just to create is wasted work."""
+    target_flag = f" --target {target_arg}" if target_arg else ""
+    return f'gh release create {tag} --notes "..." --title {tag}{target_flag}'
+
+
+def cmd_release(args: argparse.Namespace) -> int:
+    """Bare `zh release`: full preflight, then — instead of just pass/fail —
+    the commit log a release's notes get written from, plus the exact next
+    command (with the version already computed) for each bump size."""
+    result = _release_preflight(args.target)
+    if result is None:
+        return 1
+    target, _sha, releases = result
+    print(_green("PREFLIGHT PASS"))
+
+    previous_tag = releases[0].tag_name if releases else None
+    _print_commits(previous_tag)
+    print()
+
+    if previous_tag is None:
+        print("next   no previous release — write notes, pick a starting version, then:")
+        print(f"       {_gh_release_create_hint('<version>', args.target)}")
+        return 0
+
+    print("next   write release notes from the commits above, then:")
+    for part in ("patch", "minor", "major"):
+        try:
+            candidate = versioning.bump(previous_tag, part)
+        except versioning.VersionError:
+            print(
+                f"       can't auto-bump '{previous_tag}' (not a plain vX.Y.Z tag) — "
+                "pick the next version yourself"
+            )
+            break
+        print(f"       {_gh_release_create_hint(candidate, args.target)}   ({part})")
+    return 0
+
+
+def _finish_release(tag: str, target: str | None, args: argparse.Namespace) -> int:
+    notes = args.notes
+    if args.notes_file:
+        with open(args.notes_file, encoding="utf-8") as f:
+            notes = f.read()
+    if not notes:
+        print("error: pass --notes or --notes-file", file=sys.stderr)
+        return 1
+
+    try:
+        url = gh.create_release(
+            tag=tag,
+            notes=notes,
+            title=args.title or tag,
+            target=target,
+            draft=args.draft,
+            prerelease=args.prerelease,
+        )
+    except gh.ZithubError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+    print(_green(f"released: {url}"))
+    return 0
+
+
+def cmd_release_create(args: argparse.Namespace) -> int:
+    target = args.target
+    if not args.force:
+        result = _release_preflight(args.target)
+        if result is None:
+            return 1
+        target, _sha, _releases = result
+    return _finish_release(args.tag, target, args)
+
+
+def cmd_release_bump(args: argparse.Namespace) -> int:
+    """`zh release patch/minor/major`: preflight + compute the next version
+    from the latest release tag, then print it and the exact `release
+    create` command to run. Never creates the release itself — bumping the
+    version and choosing to release it are kept as two explicit steps, so
+    nothing gets published just because a version number was requested."""
+    target = args.target
+    releases: list[gh.ReleaseInfo] = []
+    if not args.force:
+        result = _release_preflight(args.target)
+        if result is None:
+            return 1
+        target, _sha, releases = result
+    else:
+        try:
+            releases = gh.recent_releases(limit=1)
+        except gh.ZithubError:
+            releases = []
+
+    if not releases:
+        print(
+            "error: no previous release to bump from — "
+            'use `zh release create <version> --notes "..."` for the first release',
+            file=sys.stderr,
+        )
+        return 1
+
+    previous_tag = releases[0].tag_name
+    try:
+        tag = versioning.bump(previous_tag, args.part)
+    except versioning.VersionError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+
+    print(f"version {previous_tag} -> {tag}")
+    _print_commits(previous_tag)
+    print()
+    print(f"next   {_gh_release_create_hint(tag, args.target)}")
+    return 0
+
+
+def _add_release_create_args(p: argparse.ArgumentParser) -> None:
+    p.add_argument("-n", "--notes", help="release notes")
+    p.add_argument("-F", "--notes-file", dest="notes_file", help="read release notes from file")
+    p.add_argument("-t", "--title", help="release title (default: the tag)")
+    p.add_argument(
+        "--target", metavar="BRANCH", help="release branch (default: repo's default branch)"
+    )
+    p.add_argument("-d", "--draft", action="store_true")
+    p.add_argument("-p", "--prerelease", action="store_true")
+    p.add_argument(
+        "--force", action="store_true", help="skip the preflight and create immediately"
+    )
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="zh", description="batched gh PR actions for AI agents"
+    )
+    sub = parser.add_subparsers(dest="command")
+    pr = sub.add_parser("pr", help="PR write actions")
+    pr_sub = pr.add_subparsers(dest="pr_command", required=True)
+
+    p_threads = pr_sub.add_parser(
+        "threads", help="list review-comment threads (with the ids reply/resolve need)"
+    )
+    _add_ref_arg(p_threads)
+    p_threads.add_argument("--all", action="store_true", help="also show resolved threads")
+    p_threads.add_argument("--path", help="only threads on a path containing this substring")
+    p_threads.set_defaults(func=cmd_threads)
+
+    p_reply = pr_sub.add_parser("reply", help="reply to a review-comment thread")
+    p_reply.add_argument("thread_id", help="thread id, from `zh pr threads`")
+    p_reply.add_argument("-b", "--body", required=True)
+    p_reply.add_argument("--resolve", action="store_true", help="also resolve the thread")
+    p_reply.set_defaults(func=cmd_reply)
+
+    p_resolve = pr_sub.add_parser("resolve", help="mark review-comment thread(s) resolved")
+    p_resolve.add_argument("thread_id", nargs="*", help="thread id(s), from `zh pr threads`")
+    p_resolve.add_argument("--all", action="store_true", help="resolve every unresolved thread")
+    p_resolve.add_argument("--path", help="with --all, only threads on a matching path")
+    p_resolve.add_argument(
+        "--pr", dest="ref", help="PR number, URL, or branch to use with --all (default: current branch's PR)"
+    )
+    p_resolve.set_defaults(func=cmd_resolve)
+
+    p_unresolve = pr_sub.add_parser("unresolve", help="reopen review-comment thread(s)")
+    p_unresolve.add_argument("thread_id", nargs="+", help="thread id(s), from `zh pr threads`")
+    p_unresolve.set_defaults(func=cmd_unresolve)
+
+    p_merge = pr_sub.add_parser(
+        "merge",
+        help="merge a PR — preflights draft/review/unresolved-threads/CI first",
+    )
+    _add_merge_args(p_merge, default_delete_branch=False)
+
+    p_ship = pr_sub.add_parser(
+        "ship",
+        help="merge + delete branch: `merge` with cleanup defaults on",
+    )
+    _add_merge_args(p_ship, default_delete_branch=True)
+
+    release = sub.add_parser(
+        "release",
+        help="preflight + what to release next (bare, or patch/minor/major); create to cut one",
+    )
+    release.add_argument(
+        "--target", metavar="BRANCH", help="release branch (default: repo's default branch)"
+    )
+    release.set_defaults(func=cmd_release)
+    release_sub = release.add_subparsers(dest="release_command")
+
+    p_release_create = release_sub.add_parser(
+        "create", help="preflight, then create the release at an explicit version"
+    )
+    p_release_create.add_argument("tag", help="release tag/version, e.g. v1.3.0")
+    _add_release_create_args(p_release_create)
+    p_release_create.set_defaults(func=cmd_release_create)
+
+    for part in ("patch", "minor", "major"):
+        p_bump = release_sub.add_parser(
+            part,
+            help=f"preflight, then show the {part}-bumped version and the gh command to create it",
+        )
+        p_bump.add_argument(
+            "--target", metavar="BRANCH", help="release branch (default: repo's default branch)"
+        )
+        p_bump.add_argument(
+            "--force", action="store_true", help="skip the preflight"
+        )
+        p_bump.set_defaults(func=cmd_release_bump, part=part)
+
+    return parser
+
+
+def main() -> None:
+    parser = build_parser()
+    args = parser.parse_args()
+    if not getattr(args, "func", None):
+        parser.print_help()
+        sys.exit(1)
+    sys.exit(args.func(args))

zithub/gh.py

@@ -0,0 +1,529 @@
+"""Thin wrappers around the `gh` CLI and its GraphQL API for PR write actions.
+
+Unlike a status tool, most of these actions delegate straight to `gh`'s own
+subprocess (inheriting stdio) so `gh`'s own flags, prompts, and error
+messages come through unchanged. The GraphQL calls (review-thread reply/
+resolve/unresolve) exist because `gh` has no first-class subcommand for
+them.
+"""
+
+from __future__ import annotations
+
+import json
+import subprocess
+from dataclasses import dataclass, field
+
+_FAILED_CONCLUSIONS = {"failure", "timed_out", "cancelled", "startup_failure", "action_required"}
+_PENDING_STATUSES = {"in_progress", "queued", "pending", "waiting", "requested"}
+
+
+class ZithubError(Exception):
+    """Raised when a required CLI is missing or a command fails."""
+
+
+def _run_result(args: list[str]) -> subprocess.CompletedProcess:
+    try:
+        result = subprocess.run(args, capture_output=True, text=True, check=False)
+    except FileNotFoundError as exc:
+        raise ZithubError(f"`{args[0]}` not found on PATH") from exc
+    if result.returncode != 0:
+        raise ZithubError(result.stderr.strip() or f"`{' '.join(args)}` failed")
+    return result
+
+
+def _run(args: list[str]) -> str:
+    return _run_result(args).stdout.strip()
+
+
+def _run_raw(args: list[str]) -> str:
+    """Like _run, but only trims the trailing newline — for output (e.g.
+    `git status --short`) whose leading whitespace on the first line is
+    meaningful and would otherwise be eaten by _run's full .strip()."""
+    return _run_result(args).stdout.rstrip("\n")
+
+
+def _run_json(args: list[str]):
+    return json.loads(_run(args))
+
+
+def _run_ok(args: list[str]) -> bool:
+    try:
+        result = subprocess.run(args, capture_output=True, text=True, check=False)
+    except FileNotFoundError:
+        return False
+    return result.returncode == 0
+
+
+def run_passthrough(args: list[str]) -> int:
+    """Run a `gh` command with stdio inherited, returning its exit code.
+
+    Used for actions where `gh`'s own output/prompts/exit code are exactly
+    what should reach the terminal (create, close, comment, review, edit) —
+    no reason to re-render what `gh` already prints well.
+    """
+    try:
+        return subprocess.run(args).returncode
+    except FileNotFoundError as exc:
+        raise ZithubError(f"`{args[0]}` not found on PATH") from exc
+
+
+@dataclass
+class RepoInfo:
+    owner: str
+    name: str
+    name_with_owner: str
+    url: str
+    default_branch: str
+
+
+def repo_info() -> RepoInfo:
+    data = _run_json(["gh", "repo", "view", "--json", "owner,name,nameWithOwner,url,defaultBranchRef"])
+    return RepoInfo(
+        owner=data["owner"]["login"],
+        name=data["name"],
+        name_with_owner=data["nameWithOwner"],
+        url=data["url"],
+        default_branch=(data.get("defaultBranchRef") or {}).get("name", "?"),
+    )
+
+
+@dataclass
+class CheckRun:
+    name: str
+    status: str
+    conclusion: str | None
+    details_url: str | None = None
+
+
+def is_failed(c: CheckRun) -> bool:
+    return (c.conclusion or "").lower() in _FAILED_CONCLUSIONS or (c.status or "").lower() == "failure"
+
+
+def is_pending(c: CheckRun) -> bool:
+    return not c.conclusion and (c.status or "").lower() in _PENDING_STATUSES
+
+
+def is_success(c: CheckRun) -> bool:
+    return (c.conclusion or "").lower() == "success" or (c.status or "").lower() == "success"
+
+
+@dataclass
+class PullRequest:
+    number: int
+    title: str
+    url: str
+    state: str
+    is_draft: bool
+    review_decision: str
+    head_ref_name: str
+    base_ref_name: str
+    checks: list[CheckRun]
+
+
+_PR_VIEW_FIELDS = (
+    "number,title,url,state,isDraft,reviewDecision,statusCheckRollup,headRefName,baseRefName"
+)
+
+
+def resolve_pr(ref: str | None = None) -> PullRequest:
+    """The PR for `ref` (number, URL, or branch), or the current branch's PR
+    if `ref` is None — same resolution `gh pr view` itself does. Raises
+    ZithubError if there's no such PR."""
+    args = ["gh", "pr", "view", "--json", _PR_VIEW_FIELDS]
+    if ref:
+        args.insert(3, ref)
+    data = _run_json(args)
+
+    checks = [
+        CheckRun(
+            name=c.get("name") or c.get("context", "?"),
+            status=c.get("status", c.get("state", "?")),
+            conclusion=c.get("conclusion"),
+            details_url=c.get("detailsUrl") or c.get("targetUrl"),
+        )
+        for c in data.get("statusCheckRollup") or []
+    ]
+    return PullRequest(
+        number=data["number"],
+        title=data["title"],
+        url=data["url"],
+        state=data["state"],
+        is_draft=data["isDraft"],
+        review_decision=data.get("reviewDecision") or "",
+        head_ref_name=data["headRefName"],
+        base_ref_name=data["baseRefName"],
+        checks=checks,
+    )
+
+
+@dataclass
+class ReviewComment:
+    id: str
+    author: str
+    created_at: str
+    body: str
+    path: str | None = None
+    line: int | None = None
+
+
+@dataclass
+class ReviewThread:
+    id: str
+    is_resolved: bool
+    comments: list[ReviewComment] = field(default_factory=list)
+
+    @property
+    def path(self) -> str | None:
+        return self.comments[0].path if self.comments else None
+
+    @property
+    def line(self) -> int | None:
+        return self.comments[0].line if self.comments else None
+
+
+_REVIEW_THREADS_QUERY = """
+query($owner: String!, $repo: String!, $pr: Int!, $after: String) {
+  repository(owner: $owner, name: $repo) {
+    pullRequest(number: $pr) {
+      reviewThreads(first: 50, after: $after) {
+        pageInfo { hasNextPage endCursor }
+        nodes {
+          id
+          isResolved
+          comments(first: 50) {
+            nodes { id body createdAt path line author { login } }
+          }
+        }
+      }
+    }
+  }
+}
+"""
+
+
+def review_threads(owner: str, repo: str, number: int) -> list[ReviewThread]:
+    """Every review-comment thread on a PR (resolved and unresolved), each
+    with its comments and GraphQL node id — the id is what `resolve`,
+    `unresolve`, and `reply` take to act on a specific thread."""
+    threads: list[ReviewThread] = []
+    after: str | None = None
+    while True:
+        args = [
+            "gh",
+            "api",
+            "graphql",
+            "-f",
+            f"query={_REVIEW_THREADS_QUERY}",
+            "-F",
+            f"owner={owner}",
+            "-F",
+            f"repo={repo}",
+            "-F",
+            f"pr={number}",
+        ]
+        if after is not None:
+            args += ["-F", f"after={after}"]
+        data = _run_json(args)
+        pr = ((data.get("data") or {}).get("repository") or {}).get("pullRequest") or {}
+        rt = pr.get("reviewThreads") or {}
+        for t in rt.get("nodes") or []:
+            comments = [
+                ReviewComment(
+                    id=c["id"],
+                    author=(c.get("author") or {}).get("login") or "?",
+                    created_at=c.get("createdAt", ""),
+                    body=c.get("body", ""),
+                    path=c.get("path"),
+                    line=c.get("line"),
+                )
+                for c in (t.get("comments") or {}).get("nodes") or []
+            ]
+            threads.append(
+                ReviewThread(id=t["id"], is_resolved=bool(t.get("isResolved")), comments=comments)
+            )
+        page_info = rt.get("pageInfo") or {}
+        if not page_info.get("hasNextPage"):
+            break
+        after = page_info.get("endCursor")
+    return threads
+
+
+def resolve_thread(thread_id: str) -> bool:
+    """Marks a review thread resolved. Returns the thread's resolved state
+    after the call (should always be True on success)."""
+    data = _run_json(
+        [
+            "gh",
+            "api",
+            "graphql",
+            "-f",
+            "query=mutation($id: ID!) { resolveReviewThread(input: {threadId: $id}) { thread { isResolved } } }",
+            "-F",
+            f"id={thread_id}",
+        ]
+    )
+    return bool((((data.get("data") or {}).get("resolveReviewThread") or {}).get("thread") or {}).get("isResolved"))
+
+
+def unresolve_thread(thread_id: str) -> bool:
+    data = _run_json(
+        [
+            "gh",
+            "api",
+            "graphql",
+            "-f",
+            "query=mutation($id: ID!) { unresolveReviewThread(input: {threadId: $id}) { thread { isResolved } } }",
+            "-F",
+            f"id={thread_id}",
+        ]
+    )
+    return bool((((data.get("data") or {}).get("unresolveReviewThread") or {}).get("thread") or {}).get("isResolved"))
+
+
+def reply_to_thread(thread_id: str, body: str) -> str:
+    """Posts `body` as a reply in an existing review thread. Returns the new
+    comment's URL."""
+    data = _run_json(
+        [
+            "gh",
+            "api",
+            "graphql",
+            "-f",
+            "query=mutation($id: ID!, $body: String!) { addPullRequestReviewThreadReply(input: {pullRequestReviewThreadId: $id, body: $body}) { comment { url } } }",
+            "-F",
+            f"id={thread_id}",
+            "-f",
+            f"body={body}",
+        ]
+    )
+    comment = (((data.get("data") or {}).get("addPullRequestReviewThreadReply") or {}).get("comment") or {})
+    return comment.get("url", "")
+
+
+# ---------------------------------------------------------------------------
+# release preflight + create — ports the github-release skill's preflight.py
+# checks (gh auth, target branch, remote sync, CI) into zh so `release
+# create` can gate on them directly instead of a separate script + a
+# hand-typed `gh release create`.
+
+_DIRTY_IGNORE = {"uv.lock"}
+
+
+def current_branch() -> str:
+    return _run(["git", "rev-parse", "--abbrev-ref", "HEAD"])
+
+
+def current_commit_sha() -> str:
+    return _run(["git", "rev-parse", "HEAD"])
+
+
+def fetch_all() -> None:
+    _run(["git", "fetch", "origin", "--prune", "--tags"])
+
+
+def remote_branch_sha(branch: str) -> str | None:
+    try:
+        return _run(["git", "rev-parse", f"origin/{branch}"])
+    except ZithubError:
+        return None
+
+
+def dirty_files() -> list[str]:
+    """Uncommitted changes (tracked or untracked) that won't be part of the
+    release since the release tag points at HEAD. `uv.lock` is excluded —
+    it's routinely rewritten by tooling and not worth flagging every time."""
+    lines = _run_raw(["git", "status", "--short"]).splitlines()
+    return [line for line in lines if line[3:].strip() not in _DIRTY_IGNORE]
+
+
+def commits_since(tag: str | None, limit: int = 50) -> list[str]:
+    """One-line log of commits since `tag` (or the last `limit` commits if
+    there's no previous release yet) — the input a release's notes get
+    written from. Best-effort: empty (never raises) if git has no history
+    or `tag` doesn't exist locally."""
+    args = (
+        ["git", "log", f"{tag}..HEAD", "--oneline", "--no-decorate"]
+        if tag
+        else ["git", "log", f"-{limit}", "--oneline", "--no-decorate"]
+    )
+    try:
+        output = _run(args)
+    except ZithubError:
+        return []
+    return output.splitlines() if output else []
+
+
+@dataclass
+class GhAccount:
+    login: str
+    active: bool
+
+
+def list_gh_accounts() -> list[GhAccount]:
+    try:
+        data = _run_json(["gh", "auth", "status", "--json", "hosts"])
+    except ZithubError:
+        return []
+    return [
+        GhAccount(login=a.get("login", ""), active=bool(a.get("active")))
+        for a in data.get("hosts", {}).get("github.com", [])
+    ]
+
+
+def _repo_visible() -> bool:
+    return _run_ok(["gh", "repo", "view", "--json", "id"])
+
+
+def ensure_gh_account_for_repo() -> str:
+    """The logged-in gh account that can actually see this repo, switching
+    to it if the currently active one can't. Tests real access via `gh repo
+    view` rather than guessing from a login/owner naming convention, so it
+    works for orgs whose name doesn't happen to embed the account's login.
+    Raises ZithubError if no logged-in account can view the repo."""
+    accounts = list_gh_accounts()
+    if not accounts:
+        raise ZithubError("no gh accounts logged in — run `gh auth login`")
+
+    if _repo_visible():
+        active = next((a for a in accounts if a.active), None)
+        return active.login if active else accounts[0].login
+
+    for account in accounts:
+        if account.active:
+            continue
+        _run(["gh", "auth", "switch", "--hostname", "github.com", "--user", account.login])
+        if _repo_visible():
+            return account.login
+
+    tried = ", ".join(a.login for a in accounts)
+    raise ZithubError(f"no logged-in gh account can view this repository (tried: {tried})")
+
+
+@dataclass
+class ReleaseInfo:
+    tag_name: str
+    name: str
+    published_at: str | None
+    is_draft: bool
+    is_prerelease: bool
+
+
+def recent_releases(limit: int = 5) -> list[ReleaseInfo]:
+    data = _run_json(
+        [
+            "gh",
+            "release",
+            "list",
+            "--limit",
+            str(limit),
+            "--json",
+            "tagName,name,publishedAt,isDraft,isPrerelease",
+        ]
+    )
+    return [
+        ReleaseInfo(
+            tag_name=r["tagName"],
+            name=r.get("name") or r["tagName"],
+            published_at=r.get("publishedAt"),
+            is_draft=r["isDraft"],
+            is_prerelease=r["isPrerelease"],
+        )
+        for r in data
+    ]
+
+
+@dataclass
+class WorkflowRun:
+    database_id: int
+    name: str
+    status: str
+    conclusion: str | None
+    url: str
+    head_sha: str | None = None
+
+
+_RUN_LIST_FIELDS = "databaseId,name,status,conclusion,url,headSha"
+
+
+def runs_for_commit(sha: str, limit: int = 100) -> list[WorkflowRun]:
+    """Workflow runs whose head commit is exactly `sha` — gates a release on
+    CI for the precise commit being tagged, not just "the latest run on this
+    branch" (which could predate a since-amended push). Filtered again
+    locally since `gh run list --commit` has been seen returning runs from
+    other commits on some repos/tokens."""
+    data = _run_json(
+        ["gh", "run", "list", "--commit", sha, "--limit", str(limit), "--json", _RUN_LIST_FIELDS]
+    )
+    return [
+        WorkflowRun(
+            database_id=r["databaseId"],
+            name=r["name"],
+            status=r["status"],
+            conclusion=r.get("conclusion"),
+            url=r["url"],
+            head_sha=r.get("headSha"),
+        )
+        for r in data
+        if r.get("headSha") == sha
+    ]
+
+
+def latest_runs_for_branch(branch: str, limit: int = 5) -> list[WorkflowRun]:
+    data = _run_json(
+        [
+            "gh",
+            "run",
+            "list",
+            "--branch",
+            branch,
+            "--limit",
+            str(limit),
+            "--json",
+            _RUN_LIST_FIELDS,
+        ]
+    )
+    return [
+        WorkflowRun(
+            database_id=r["databaseId"],
+            name=r["name"],
+            status=r["status"],
+            conclusion=r.get("conclusion"),
+            url=r["url"],
+            head_sha=r.get("headSha"),
+        )
+        for r in data
+    ]
+
+
+def run_failure_log(database_id: int, lines: int = 40) -> str | None:
+    """Best-effort tail of a failed run's log — best-effort since a run can
+    fail in ways that leave no per-step log (infra failure, cancellation)."""
+    try:
+        text = _run(["gh", "run", "view", str(database_id), "--log-failed"])
+    except ZithubError:
+        return None
+    if not text:
+        return None
+    return "\n".join(text.splitlines()[-lines:])
+
+
+def create_release(
+    tag: str,
+    notes: str,
+    title: str | None = None,
+    target: str | None = None,
+    draft: bool = False,
+    prerelease: bool = False,
+) -> str:
+    """Creates the GitHub release (and its tag) via `gh release create`.
+    Returns the release URL."""
+    cmd = ["gh", "release", "create", tag, "--notes", notes]
+    if title:
+        cmd += ["--title", title]
+    if target:
+        cmd += ["--target", target]
+    if draft:
+        cmd.append("--draft")
+    if prerelease:
+        cmd.append("--prerelease")
+    return _run(cmd)

zithub/versioning.py

@@ -0,0 +1,32 @@
+"""Semver tag bumping — pure logic, no subprocess calls."""
+
+from __future__ import annotations
+
+import re
+
+_SEMVER_RE = re.compile(r"^(?P<prefix>[vV])?(?P<major>\d+)\.(?P<minor>\d+)\.(?P<patch>\d+)$")
+
+
+class VersionError(Exception):
+    """Raised when a tag doesn't parse as a plain vX.Y.Z / X.Y.Z semver tag."""
+
+
+def bump(tag: str, part: str) -> str:
+    """`tag` with its major/minor/patch component incremented and the
+    components after it reset to 0, preserving a leading "v" if present.
+    `part` is one of "major", "minor", "patch"."""
+    match = _SEMVER_RE.match(tag)
+    if not match:
+        raise VersionError(
+            f"'{tag}' doesn't look like a plain semver tag (vX.Y.Z) — pass the next version explicitly"
+        )
+    major, minor, patch = int(match["major"]), int(match["minor"]), int(match["patch"])
+    if part == "major":
+        major, minor, patch = major + 1, 0, 0
+    elif part == "minor":
+        minor, patch = minor + 1, 0
+    elif part == "patch":
+        patch += 1
+    else:
+        raise ValueError(f"unknown part: {part!r}")
+    return f"{match['prefix'] or ''}{major}.{minor}.{patch}"

zithub-0.1.0.dist-info/METADATA

@@ -0,0 +1,124 @@
+Metadata-Version: 2.4
+Name: zithub
+Version: 0.1.0
+Summary: Batched gh CLI actions for PR workflows: merge preflight, review-thread reply/resolve, and more in one call
+Keywords: git,github,cli,pull-request,ci,gh
+Author: Ville Vainio
+Author-email: Ville Vainio <vivainio@gmail.com>
+License-Expression: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Project-URL: Homepage, https://github.com/vivainio/zithub
+Project-URL: Repository, https://github.com/vivainio/zithub
+Project-URL: Issues, https://github.com/vivainio/zithub/issues
+Description-Content-Type: text/markdown
+
+# zithub
+
+`zh` — batched `gh` PR actions for AI agents, for the two things plain `gh`
+can't already do in a single call: acting on PR review-comment threads (no
+`gh` subcommand exists for these at all), and merging with a real preflight
+(draft/review-decision/unresolved-threads/CI, checked and merged in one
+call instead of chained separately). Where
+[wazup](https://github.com/vivainio/wazup) is the read-only "what's up with
+this repo" status tool, `zh` is this narrower write-side complement — it
+deliberately does *not* wrap `gh pr create/close/comment/review/edit`,
+since those are already one `gh` call each and an agent that already knows
+`gh` gains nothing from a second name for the same thing.
+
+Requires the [GitHub CLI](https://cli.github.com/) (`gh`) installed and
+authenticated (`gh auth login`).
+
+## Commands
+
+```
+zh pr threads    # list review-comment threads (with the ids below)
+zh pr reply      # reply to a review-comment thread, optionally --resolve
+zh pr resolve    # mark thread(s) resolved, by id or --all
+zh pr unresolve  # reopen thread(s)
+
+zh pr merge      # merge a PR
+zh pr ship       # merge + delete branch (same as `merge --delete-branch`)
+
+zh release                    # preflight, then commits + the gh command for each next version
+zh release patch/minor/major  # preflight, then just that one bumped version + gh command
+zh release create             # preflight, then actually create at an explicit version
+```
+
+`threads`/`reply`/`resolve`/`unresolve` exist because `gh` has no
+subcommand for review threads at all — they go through `gh api graphql`
+directly (`reviewThreads`, `resolveReviewThread`, `unresolveReviewThread`,
+`addPullRequestReviewThreadReply`). Run `zh pr threads` to see each
+thread's id, then act on it:
+
+```
+zh pr threads                       # unresolved threads on the current branch's PR
+zh pr reply T_kwDOA... -b "fixed in a1b2c3d" --resolve
+zh pr resolve --all --path src/     # resolve every unresolved thread under src/
+```
+
+`zh pr merge` (and `zh pr ship`, which is the same thing with
+`--delete-branch` on by default) bundles what would otherwise be a
+draft/review-decision/unresolved-thread/CI check spread across several
+calls into one preflight, then merges only if everything's clean:
+
+```
+zh pr merge                 # preflight, waiting on any pending checks, then squash-merge
+zh pr ship                  # same, plus delete the branch afterward
+zh pr merge --no-wait        # fail fast instead of polling pending checks
+zh pr merge --force          # skip the preflight and merge immediately
+zh pr merge --method rebase --keep-branch
+```
+
+`zh release` (bare, or `patch`/`minor`/`major`) ports the checks from the
+`github-release` skill's `preflight.py` — the right gh account is active
+(tested by actually trying to view the repo, not by guessing from a
+login/owner naming convention), the current branch matches the release
+target, local HEAD matches `origin/<target>` exactly, and CI is green on
+that exact commit (falling back to the branch's latest runs if no run
+exists yet for the commit, and proceeding on judgement if none exist at
+all). A dirty worktree only warns — it isn't part of the release either
+way, since the tag points at HEAD.
+
+Past the preflight it's read-only: it never creates anything itself. It
+shows the commit log a release's notes get written from, and prints the
+exact `gh release create ...` command to run once notes are ready — not
+`zh release create`, since the preflight (including the CI wait) was just
+run right here and redoing it a moment later would be wasted work.
+`patch`/`minor`/`major` fetch the latest release tag and compute one
+specific bump; bare `zh release` shows all three:
+
+```
+zh release                          # -> gh release create <next patch/minor/major> ...
+zh release patch                    # -> just the patch bump
+zh release patch --target release-2.0
+```
+
+`zh release create` is the one command that actually publishes — it runs
+the same preflight itself first (unless `--force`), so it's also safe to
+call directly without a prior `zh release`:
+
+```
+zh release create v1.3.0 -n "$(cat notes.md)"
+zh release create v2.0.0-rc1 --prerelease --force   # skip the preflight
+```
+
+## Install
+
+```
+uv tool install zithub
+```
+
+## License
+
+MIT

zithub-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+zithub/__init__.py,sha256=oKsCpoiQSSXx57DGs2VfYzeO1ukJQxdGnV-2hC3BI0M,42
+zithub/cli.py,sha256=DK-l1Lsh4xdi4rjh0OPX4mqYmeDx4m14P7OA3EE0q8w,22630
+zithub/gh.py,sha256=GXm_jGLQPjbjLzGDLWvUi0s3lMLp5g8sbrcv94SxPgY,15897
+zithub/versioning.py,sha256=7a_pZLRWNVGDJ3ZdcXxKGysFULvhoPiFyc25mEMnfKU,1135
+zithub-0.1.0.dist-info/WHEEL,sha256=-i9oRNYVXXZJUIYl5zclLIg6onEb0NLibTX34uln84w,81
+zithub-0.1.0.dist-info/entry_points.txt,sha256=M3-unQLWLE8cNBsh2cObkQpM1kB9Tzd5Htopq6lMQg0,36
+zithub-0.1.0.dist-info/METADATA,sha256=VbP-dKqci6uXVIPmILCnrzN9EqQvKPdXGK-FRfzNSLI,5334
+zithub-0.1.0.dist-info/RECORD,,

zithub-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.12.13
+Root-Is-Purelib: true
+Tag: py3-none-any

zithub-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+zh = zithub:main
+