zithub 0.1.0__tar.gz → 0.2.0__tar.gz

zithub-0.2.0/PKG-INFO

@@ -0,0 +1,186 @@
+Metadata-Version: 2.4
+Name: zithub
+Version: 0.2.0
+Summary: What's up with this repo, right now, plus batched gh PR/release actions: status, CI, merge preflight, review-thread reply/resolve, and more
+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` — what's up with this repo, right now, plus batched `gh` PR and release
+actions for AI agents. A standalone `gh`/`git` CLI: bare `zh` gives repo,
+branch, local, PR, and CI status in one shot (no separate status tool
+required), and the rest covers what plain `gh` can't already do in a single
+call — acting on PR review-comment threads (no `gh` subcommand exists for
+these at all), merging with a real preflight
+(draft/review-decision/unresolved-threads/CI, checked and merged in one
+call instead of chained separately), and release preflight/creation. The
+status/CI/PR/my/review/issues reporting is ported from
+[wazup](https://github.com/vivainio/wazup), so `zh` doesn't need wazup
+installed alongside it. 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                # repo, branch, local, PR, and CI status in one shot
+                  # (also recent branches/worktrees on the default branch)
+zh ci             # just the CI status for the current branch/PR
+zh pr             # current branch's PR: status, checks, and review comment
+                  # threads (unresolved by default; --all also shows resolved)
+zh my             # your open PRs in this repo, or recent PR activity outside one
+zh review         # PRs awaiting your review, updated in the last 7 days
+zh issues         # your open issues in this repo, or recent activity outside one
+
+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 check      # target branch, and whether the PR references a ticket
+
+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
+
+zh repos           # local checkouts zh has seen, most-recently-seen first
+zh install-skills  # install the zh Claude Code skill
+```
+
+Add `-w`/`--why` to `zh`, `zh ci`, or `zh pr` to drill into a failing check
+— prints the tail of the failing job's log, right up to the error, instead
+of just a pass/fail icon.
+
+`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 check` surfaces what you'd otherwise have to open the PR on the web
+(or find a local clone) to see: the base branch it's targeting (no
+judgment — just shown, since only you know whether it's the wrong one),
+its local checkout if `zh repos` has seen one for that branch — warning if
+that checkout is dirty, since switching branches or pulling there would be
+risky — and whether the title/body references a ticket at all: a GitHub
+issue ref (`#123`, `Fixes #123`), any URL (covers a Jira/Linear/etc. link),
+or a bare Jira-style key (`ABC-123`, flagged with a suggestion to link it
+directly). Exits non-zero if no ticket reference is found.
+
+Typically called with one or more PR URLs directly (an owner/repo parsed
+right out of the URL, so it works from anywhere — not just a checkout of
+that repo), rather than a bare number, which only resolves against the
+current directory's repo:
+
+```
+zh pr check                                          # current branch's PR
+zh pr check https://github.com/acme/widgets/pull/42
+zh pr check https://github.com/.../pull/42 https://github.com/.../pull/43   # a summary block per PR
+```
+
+`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`) checks: the active gh
+account matches the repo's owner (same convention `wazup` uses — a
+logged-in account whose login, or the org half of a `name_OrgName`
+corporate-SSO login, matches origin's owner; best-effort and never blocks
+the release if nothing matches), 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 `zh release create ...` command to run once notes are ready. That
+command skips its own preflight by default, so running it right after
+`zh release` doesn't redo the CI wait that was just run here.
+`patch`/`minor`/`major` fetch the latest release tag and compute one
+specific bump; bare `zh release` shows all three:
+
+```
+zh release                          # -> zh 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
+requires release notes (`-n`/`--notes` or `-F`/`--notes-file` — one of
+them, always), and after creating the GitHub release it also polls for and
+waits on any workflow run(s) triggered by that release (e.g. a PyPI
+publish job), reporting success or failure instead of leaving that for the
+caller to check separately. A repo with no such workflow just proceeds —
+it's not treated as a failure. The preflight is opt-in via `--preflight`,
+for when you're calling it directly without a prior `zh release`:
+
+```
+zh release create v1.3.0 -n "$(cat notes.md)"
+zh release create v2.0.0-rc1 --prerelease --preflight   # check first, since there was no prior `zh release`
+```
+
+Every command above that needs `gh` also registers the checkout it ran in
+— path, repo, branch — into a local registry at
+`~/.local/share/zithub/repos.jsonl`, ported from wazup's own (a separate
+database, same design). `zh repos` lists what's been seen, letting an
+agent find a local checkout of a repo by name instead of guessing paths or
+re-cloning; two worktrees or clones of the same repo, at different paths,
+show up as separate entries with their own branch:
+
+```
+zh repos          # everything seen, most-recently-seen first
+zh repos zithub   # only checkouts whose repo name or path contains "zithub"
+```
+
+## Install
+
+```
+uv tool install zithub
+```
+
+## License
+
+MIT

zithub-0.2.0/README.md

@@ -0,0 +1,161 @@
+# zithub
+
+`zh` — what's up with this repo, right now, plus batched `gh` PR and release
+actions for AI agents. A standalone `gh`/`git` CLI: bare `zh` gives repo,
+branch, local, PR, and CI status in one shot (no separate status tool
+required), and the rest covers what plain `gh` can't already do in a single
+call — acting on PR review-comment threads (no `gh` subcommand exists for
+these at all), merging with a real preflight
+(draft/review-decision/unresolved-threads/CI, checked and merged in one
+call instead of chained separately), and release preflight/creation. The
+status/CI/PR/my/review/issues reporting is ported from
+[wazup](https://github.com/vivainio/wazup), so `zh` doesn't need wazup
+installed alongside it. 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                # repo, branch, local, PR, and CI status in one shot
+                  # (also recent branches/worktrees on the default branch)
+zh ci             # just the CI status for the current branch/PR
+zh pr             # current branch's PR: status, checks, and review comment
+                  # threads (unresolved by default; --all also shows resolved)
+zh my             # your open PRs in this repo, or recent PR activity outside one
+zh review         # PRs awaiting your review, updated in the last 7 days
+zh issues         # your open issues in this repo, or recent activity outside one
+
+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 check      # target branch, and whether the PR references a ticket
+
+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
+
+zh repos           # local checkouts zh has seen, most-recently-seen first
+zh install-skills  # install the zh Claude Code skill
+```
+
+Add `-w`/`--why` to `zh`, `zh ci`, or `zh pr` to drill into a failing check
+— prints the tail of the failing job's log, right up to the error, instead
+of just a pass/fail icon.
+
+`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 check` surfaces what you'd otherwise have to open the PR on the web
+(or find a local clone) to see: the base branch it's targeting (no
+judgment — just shown, since only you know whether it's the wrong one),
+its local checkout if `zh repos` has seen one for that branch — warning if
+that checkout is dirty, since switching branches or pulling there would be
+risky — and whether the title/body references a ticket at all: a GitHub
+issue ref (`#123`, `Fixes #123`), any URL (covers a Jira/Linear/etc. link),
+or a bare Jira-style key (`ABC-123`, flagged with a suggestion to link it
+directly). Exits non-zero if no ticket reference is found.
+
+Typically called with one or more PR URLs directly (an owner/repo parsed
+right out of the URL, so it works from anywhere — not just a checkout of
+that repo), rather than a bare number, which only resolves against the
+current directory's repo:
+
+```
+zh pr check                                          # current branch's PR
+zh pr check https://github.com/acme/widgets/pull/42
+zh pr check https://github.com/.../pull/42 https://github.com/.../pull/43   # a summary block per PR
+```
+
+`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`) checks: the active gh
+account matches the repo's owner (same convention `wazup` uses — a
+logged-in account whose login, or the org half of a `name_OrgName`
+corporate-SSO login, matches origin's owner; best-effort and never blocks
+the release if nothing matches), 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 `zh release create ...` command to run once notes are ready. That
+command skips its own preflight by default, so running it right after
+`zh release` doesn't redo the CI wait that was just run here.
+`patch`/`minor`/`major` fetch the latest release tag and compute one
+specific bump; bare `zh release` shows all three:
+
+```
+zh release                          # -> zh 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
+requires release notes (`-n`/`--notes` or `-F`/`--notes-file` — one of
+them, always), and after creating the GitHub release it also polls for and
+waits on any workflow run(s) triggered by that release (e.g. a PyPI
+publish job), reporting success or failure instead of leaving that for the
+caller to check separately. A repo with no such workflow just proceeds —
+it's not treated as a failure. The preflight is opt-in via `--preflight`,
+for when you're calling it directly without a prior `zh release`:
+
+```
+zh release create v1.3.0 -n "$(cat notes.md)"
+zh release create v2.0.0-rc1 --prerelease --preflight   # check first, since there was no prior `zh release`
+```
+
+Every command above that needs `gh` also registers the checkout it ran in
+— path, repo, branch — into a local registry at
+`~/.local/share/zithub/repos.jsonl`, ported from wazup's own (a separate
+database, same design). `zh repos` lists what's been seen, letting an
+agent find a local checkout of a repo by name instead of guessing paths or
+re-cloning; two worktrees or clones of the same repo, at different paths,
+show up as separate entries with their own branch:
+
+```
+zh repos          # everything seen, most-recently-seen first
+zh repos zithub   # only checkouts whose repo name or path contains "zithub"
+```
+
+## Install
+
+```
+uv tool install zithub
+```
+
+## License
+
+MIT

{zithub-0.1.0 → zithub-0.2.0}/pyproject.toml

@@ -1,7 +1,7 @@
 [project]
 name = "zithub"
-version = "0.1.0"
-description = "Batched gh CLI actions for PR workflows: merge preflight, review-thread reply/resolve, and more in one call"
+version = "0.2.0"
+description = "What's up with this repo, right now, plus batched gh PR/release actions: status, CI, merge preflight, review-thread reply/resolve, and more"
 readme = "README.md"
 license = "MIT"
 requires-python = ">=3.10"
@@ -52,3 +52,7 @@ dev = [
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]
+
+[[tool.uv.index]]
+url = "https://pypi.org/simple"
+default = true

{zithub-0.1.0 → zithub-0.2.0}/pyproject.toml.orig

@@ -1,7 +1,7 @@
 [project]
 name = "zithub"
-version = "0.1.0"
-description = "Batched gh CLI actions for PR workflows: merge preflight, review-thread reply/resolve, and more in one call"
+version = "0.2.0"
+description = "What's up with this repo, right now, plus batched gh PR/release actions: status, CI, merge preflight, review-thread reply/resolve, and more"
 readme = "README.md"
 authors = [
     { name = "Ville Vainio", email = "vivainio@gmail.com" }
@@ -44,3 +44,7 @@ dev = [
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]
+
+[[tool.uv.index]]
+url = "https://pypi.org/simple"
+default = true