gh-upstream-watch 0.1.0__tar.gz

gh_upstream_watch-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Colin McNamara LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

gh_upstream_watch-0.1.0/PKG-INFO

@@ -0,0 +1,266 @@
+Metadata-Version: 2.4
+Name: gh-upstream-watch
+Version: 0.1.0
+Summary: Read-only alerts for your upstream work: tells you the next action when a maintainer gate, a competing PR, or a review moves.
+Keywords: github,gh-extension,open-source,notifications,maintainers
+Author: Colin McNamara
+Author-email: Colin McNamara <colin@2cups.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Environment :: Console
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Version Control :: Git
+Requires-Python: >=3.9
+Project-URL: Homepage, https://github.com/colinmcnamara/gh-upstream-watch
+Project-URL: Issues, https://github.com/colinmcnamara/gh-upstream-watch/issues
+Project-URL: Changelog, https://github.com/colinmcnamara/gh-upstream-watch/blob/main/CHANGELOG.md
+Description-Content-Type: text/markdown
+
+# gh-upstream-watch
+
+Read-only alerts for your upstream work: tells you the next action when a maintainer gate, a
+competing PR, or a review moves.
+
+If you contribute to projects you do not maintain, the important events are easy to miss in the
+notification stream: a maintainer accepts your proposal and now expects you to claim it, someone
+else opens a PR that closes the issue you are working on, your closed issue is reopened. This tool
+polls the issues and PRs you are involved in, compares each one with the last run, and prints (and
+optionally pops up) one line per change, worded as what to do next.
+
+## What makes it different
+
+1. **Next-action alerts.** Rule packs turn generic changes into instructions:
+   `ACCEPTED by @maint: comment /assign now`,
+   `COMPETING PR #401 (by @monalisa) says Closes #390: check scope before /assign`,
+   `REOPENED: claim it`. A gate only counts when the commenter is authorized
+   (a login allowlist, or a maintainer author association), so a drive-by `/accept` is ignored.
+2. **Read-only by construction.** Every built-in GitHub call goes through one function that runs
+   `gh api --method GET`. The tool itself never comments, labels, assigns or pushes. (A `--hook`,
+   a `$GH_UPSTREAM_WATCH_NOTIFY` command or a `--webhook` you configure is your own code or
+   endpoint and can do anything; see Trust below.)
+3. **Never silently current.** A failed page, a timeout, or a search GitHub marks
+   `incomplete_results` makes that item *unknown for this run*: its saved state is not advanced,
+   so the change alerts on the next good run instead of being swallowed.
+4. **Quiet by default.** The first run sends no alerts; it prints one "seed run" line to stderr. Bots are filtered from comment counts.
+   Megathreads you list (for example `[Community]` issues) alert only on comments that `@`-name you.
+
+## Demo
+
+Two runs against recorded, synthetic GitHub data (`scripts/demo.sh`; no network, and the stand-in
+`gh` refuses anything but GET). You are `@octocat`. The first run seeds; between the runs a
+collaborator posts comment 101 (`/accept`, on the second page of comments; it alerts as the gate,
+not again as "1 new comment"), a bot comments,
+`@monalisa` opens a PR that says `Closes: #390`, your closed issue is reopened, your PR is approved
+(and drops out of search results, but it is still open, so it stays watched), and someone names
+you in a megathread, and a review request arrives. A mention in `acme/gadgets` is ignored because
+notifications follow `--repos`. This is the real output:
+
+```text
+$ gh-upstream-watch --repos acme/widgets --packs-dir tests/fixtures/packs --notify none
+2026-09-30 08:24 seed run: watching 4 item(s); 1 alert(s) suppressed. Alerts start after the first complete run.
+
+$ gh-upstream-watch --repos acme/widgets --packs-dir tests/fixtures/packs --notify none
+[2026-09-30 08:24] acme/widgets#388 Document the retry flag: REOPENED: claim it (https://github.com/acme/widgets/issues/388)
+[2026-09-30 08:24] acme/widgets#390 Widget spins forever on an empty config: ACCEPTED by @maint: comment /assign now (https://github.com/acme/widgets/issues/390)
+[2026-09-30 08:24] acme/widgets#390 Widget spins forever on an empty config: COMPETING PR #401 (by @monalisa) says Closes #390: check scope before /assign (https://github.com/acme/widgets/pull/401)
+[2026-09-30 08:24] acme/widgets#392 Add retry backoff: review: @maint APPROVED (https://github.com/acme/widgets/pull/392)
+[2026-09-30 08:24] acme/widgets#395 [Community] Weekly sync thread: 1 comment(s) naming you (https://github.com/acme/widgets/issues/395)
+[2026-09-30 08:24] acme/widgets: someone requested your review: Tighten lint config (https://github.com/acme/widgets/pull/14)
+```
+
+The same two runs are a golden test (`tests/test_run.py`).
+
+## Install
+
+Requires the [GitHub CLI](https://cli.github.com) (`gh auth login` done) and Python 3.9 or newer.
+No other dependencies.
+
+```sh
+uv tool install gh-upstream-watch
+# or
+pipx install gh-upstream-watch
+# or, as a gh extension (runs from a checkout with your python3):
+gh extension install colinmcnamara/gh-upstream-watch    # then: gh upstream-watch --help
+```
+
+## Use
+
+```sh
+gh-upstream-watch init --repos acme/widgets       # writes ~/.config/gh-upstream-watch/config.json
+gh-upstream-watch --dry-run                       # one pass, print only, save nothing
+gh-upstream-watch                                 # one pass: alerts, then save state
+gh-upstream-watch status                          # what the state file knows
+```
+
+Each invocation is one pass. Schedule it; the tool prints a ready scheduler entry that points at
+the interpreter and script you ran it with:
+
+```sh
+gh-upstream-watch --print-plist   > ~/Library/LaunchAgents/local.gh-upstream-watch.plist   # macOS
+gh-upstream-watch --print-systemd                                                          # Linux
+gh-upstream-watch --print-cron
+```
+
+What one pass checks:
+
+- every open issue and PR in `repos` you are involved in (author, assignee, commenter, mentioned),
+  those closed in the last 14 days, `extras` (`owner/repo#n`), and anything already watched that
+  is still open. The saved state of a closed item is kept for `baseline_days` (90) after it was
+  last checked, so a reopen within that time alerts; after that it counts as new and seeds quietly;
+- unread GitHub notifications that mention you, request your review, or assign you, in the watched
+  repos (exact names; set `notification_repos` to `["*"]` for every repo, or to globs). This needs a
+  token with the `notifications` scope: `gh auth refresh -s notifications` if they come back 403;
+- claim boards defined by a pack (a pinned issue that lists claimable tasks), for `claim_groups`.
+
+Exit status: 0 when every check completed, 1 when something was unknown this run (logged as
+`unknown this run`; `gh` missing or signed out also lands here, with the fix printed), 2 for a
+config, argument or rule-pack error (including no repos configured), 3 when another run holds the
+state lock. `status` is a doctor: it checks `gh` and your login, shows the config path, the packs
+applied to each repo, the last complete run, and what the last run could not check.
+
+## Configuration
+
+JSON, at `$XDG_CONFIG_HOME/gh-upstream-watch/config.json` (default `~/.config/...`). Precedence:
+command line, then environment (`GH_UPSTREAM_WATCH_CONFIG`, `GH_UPSTREAM_WATCH_REPOS` comma list,
+`GH_UPSTREAM_WATCH_STATE`), then the file. Unknown keys are errors.
+
+```json
+{
+  "repos": ["acme/widgets", "acme/gadgets"],
+  "extras": ["octo-org/octo-repo#12"],
+  "notify": "auto",
+  "webhook": null,
+  "hook": null,
+  "packs_dirs": [],
+  "claim_groups": [],
+  "recent_closed_days": 14,
+  "retention_days": 30,
+  "baseline_days": 90,
+  "notification_repos": null,
+  "login": "octocat",
+  "bots": [],
+  "slack": {"enabled": false}
+}
+```
+
+Notifications: stdout always (text with the URL, or `--json` for JSON lines). `notify: auto` uses
+`$GH_UPSTREAM_WATCH_NOTIFY` (a command that gets the alert JSON on stdin) if set, else
+`terminal-notifier`, `notify-send`, or `osascript` (macOS; the URL is kept in the visible text,
+since those banners cannot open a link; the text is passed as arguments, never as script).
+`--webhook URL` also POSTs `{"text": ..., "alert": ...}`; it must be https (http only to
+localhost), and only a 2xx answer counts; a redirect is a failure and is not followed. Each alert is delivered to each destination separately; a destination that fails
+stays in the outbox and is retried on later runs (up to 5), without printing the alert again.
+Only `https://github.com/` links (and `https://*.slack.com/` for Slack) are passed to a notifier
+to open; a link from comment text that points elsewhere is replaced by the item's own URL.
+
+## Rule packs
+
+Packs are local JSON data, loaded from the bundled `packs/`, then
+`~/.config/gh-upstream-watch/packs/`, then any `--packs-dir`. A pack with the same `id` replaces
+an earlier one. Packs are never read from a watched repository: the repo you are watching must not
+be able to decide what you are told. Bundled: `generic` (wording for every repo) and
+`vllm-semantic-router` (the `/accept` then `/assign` flow of `vllm-project/semantic-router`).
+
+```json
+{
+  "id": "acme",
+  "repos": ["acme/*"],
+  "gates": [{
+    "id": "accept",
+    "comment": "^/accept\\b",
+    "authorized_by": {"associations": ["MEMBER", "OWNER"], "logins": []},
+    "then": "^/assign\\b",
+    "alert": "ACCEPTED by @{actor}: comment /assign now",
+    "alert_done": "ACCEPTED by @{actor}"
+  }],
+  "label_transitions": [{"id": "stuck", "assigned_to_me": true, "has": ["accepted"], "lacks": ["in-progress"],
+                         "alert": "in-progress label missing"}],
+  "quiet_titles": ["^\\[Community\\]"],
+  "messages": {"reopened": "REOPENED: claim it",
+               "competing_pr": "COMPETING PR #{number} (by @{author}) says Closes #{target}: check scope"}
+}
+```
+
+A gate matches only at the start of a comment (not a quoted line further down). If a gate lists
+`logins`, only those logins count. Otherwise only its `associations` count, `OWNER` and
+`COLLABORATOR` by default; `MEMBER` is not a default because an organization member can have
+read-only access. Author association alone cannot prove who may run a gate, so add the
+maintainers' logins to your copy of a pack when you know them. On first sight of an item, gates
+are checked too: an `/accept` already waiting alerts once. `then` is your own follow-up command; once you have posted it the alert drops the
+call to action. See `CONTRIBUTING.md` for the full schema and how to add a pack with a fixture.
+
+For anything a pack cannot express, `--hook /abs/path` runs your program once per
+watched item that has a previous fingerprint (no shell, 30 s timeout) with `{"key", "repo", "number", "me", "old", "new"}` on
+stdin; each stdout line `{"message": "...", "kind": "...", "url": "..."}` becomes an alert.
+
+## Reliability
+
+- Full pagination for search, comments, reviews, timeline and notifications. A search over
+  GitHub's 1,000-result cap is reported as unknown with a warning (no partitioning yet).
+- One failing item never loses the run; the state file is always saved.
+- The first run is silent, and the "seeded" flag is set only after a run in which every check
+  succeeded, so a half-failed first run cannot flood you later.
+- State writes are atomic (temp file, fsync, rename) under an exclusive lock. A corrupt state file
+  is moved aside and the next run re-seeds quietly.
+- Alerts are written to an outbox in the state file before delivery; a crash in between
+  re-delivers them on the next run (at least once; a duplicate is possible, a loss is not).
+- The state file is written mode 0600 (it holds titles and URLs from private repos).
+- Seen-id stores are pruned after `retention_days`, only after a complete pass, and never for an
+  id GitHub still returns.
+
+Known limits: polling cannot see an event GitHub never exposes, or a state that changes twice
+between polls. Notification asks use GitHub's `participating` filter, so an ask GitHub does not
+count as participating is not seen there (the issue and PR checks still run).
+
+## Trust
+
+The tool only reads GitHub. Three things you configure are trusted local code or endpoints:
+`--hook` runs a program with your permissions, `$GH_UPSTREAM_WATCH_NOTIFY` runs a command, and
+`--webhook` sends every alert (titles, logins, URLs) to that URL. Rule packs are data, but only
+load packs you have read. A failing hook makes that item unknown for the run, so nothing is lost.
+
+## Slack (optional, off by default)
+
+`--slack` (or `"slack": {"enabled": true}`) adds Slack mentions and replies in your threads. Read
+this before enabling it:
+
+- It needs [Claude Code](https://docs.anthropic.com/en/docs/claude-code) and the official Slack
+  plugin, already signed in. Each check is one headless `claude -p` call with a small model
+  (`haiku` by default), no built-in tools (`--tools ""`), only the Slack search and read-thread
+  tools allowed, no user or project settings, an empty temporary working directory, and a minimal
+  environment (no `GH_TOKEN`). That call costs money or plan usage; `every_minutes` (default 25)
+  throttles it.
+- Model output is untrusted. The answer must be exactly a JSON array. Each item must carry a
+  Slack channel id, a message ts and the text, plus proof: the raw `<@you>` tag for a mention, or
+  the ts of your own message for a thread reply. Items without proof, outside `channels` (when
+  set), or older than `days` are dropped. Be clear about what that proves: the proof fields are
+  themselves model output, so a prompt injection in a Slack message can forge them. The damage is
+  limited because the model has no tools except two Slack read tools, and only
+  `https://*.slack.com/` links are ever passed to a notifier.
+- Slack failures are counted in their own state (`status` shows them) and never make the GitHub
+  pass incomplete or block it.
+- Nothing is shipped: `user`, `query` and `channels` come from your config. The query is a prompt
+  with `{user}` and `{days}` placeholders; it must tell the model to output the fields above:
+
+```json
+"slack": {
+  "enabled": true,
+  "user": "UEXAMPLE1",
+  "days": 14,
+  "every_minutes": 25,
+  "channels": [],
+  "query": "You are a read-only Slack checker for user {user}. Search for messages from the last {days} days that mention <@{user}>, and replies to threads {user} posted in. Output ONLY a JSON array; each element: {{\"channel\": \"#name\", \"channel_id\": \"C...\", \"ts\": \"...\", \"author\": \"...\", \"kind\": \"mention\" or \"thread_reply\", \"your_ts\": \"ts of {user}'s own message in the thread, else empty\", \"evidence\": \"the raw mention text, e.g. <@{user}|name>, else empty\", \"text\": \"first 120 characters\", \"link\": \"permalink or empty\"}}. If there is nothing, output []."
+}
+```
+
+## Migrating from the single-file script
+
+`gh-upstream-watch migrate --from OLD_STATE.json --state NEW_STATE.json --claim-repo owner/repo`
+converts a v0 state file (one flat dict of fingerprints plus `_notifications`, `_slack`,
+`_claimable`). Fingerprints and seen ids are kept, so nothing re-alerts and nothing re-seeds.
+
+## License
+
+MIT. See `LICENSE`.

gh_upstream_watch-0.1.0/README.md

@@ -0,0 +1,246 @@
+# gh-upstream-watch
+
+Read-only alerts for your upstream work: tells you the next action when a maintainer gate, a
+competing PR, or a review moves.
+
+If you contribute to projects you do not maintain, the important events are easy to miss in the
+notification stream: a maintainer accepts your proposal and now expects you to claim it, someone
+else opens a PR that closes the issue you are working on, your closed issue is reopened. This tool
+polls the issues and PRs you are involved in, compares each one with the last run, and prints (and
+optionally pops up) one line per change, worded as what to do next.
+
+## What makes it different
+
+1. **Next-action alerts.** Rule packs turn generic changes into instructions:
+   `ACCEPTED by @maint: comment /assign now`,
+   `COMPETING PR #401 (by @monalisa) says Closes #390: check scope before /assign`,
+   `REOPENED: claim it`. A gate only counts when the commenter is authorized
+   (a login allowlist, or a maintainer author association), so a drive-by `/accept` is ignored.
+2. **Read-only by construction.** Every built-in GitHub call goes through one function that runs
+   `gh api --method GET`. The tool itself never comments, labels, assigns or pushes. (A `--hook`,
+   a `$GH_UPSTREAM_WATCH_NOTIFY` command or a `--webhook` you configure is your own code or
+   endpoint and can do anything; see Trust below.)
+3. **Never silently current.** A failed page, a timeout, or a search GitHub marks
+   `incomplete_results` makes that item *unknown for this run*: its saved state is not advanced,
+   so the change alerts on the next good run instead of being swallowed.
+4. **Quiet by default.** The first run sends no alerts; it prints one "seed run" line to stderr. Bots are filtered from comment counts.
+   Megathreads you list (for example `[Community]` issues) alert only on comments that `@`-name you.
+
+## Demo
+
+Two runs against recorded, synthetic GitHub data (`scripts/demo.sh`; no network, and the stand-in
+`gh` refuses anything but GET). You are `@octocat`. The first run seeds; between the runs a
+collaborator posts comment 101 (`/accept`, on the second page of comments; it alerts as the gate,
+not again as "1 new comment"), a bot comments,
+`@monalisa` opens a PR that says `Closes: #390`, your closed issue is reopened, your PR is approved
+(and drops out of search results, but it is still open, so it stays watched), and someone names
+you in a megathread, and a review request arrives. A mention in `acme/gadgets` is ignored because
+notifications follow `--repos`. This is the real output:
+
+```text
+$ gh-upstream-watch --repos acme/widgets --packs-dir tests/fixtures/packs --notify none
+2026-09-30 08:24 seed run: watching 4 item(s); 1 alert(s) suppressed. Alerts start after the first complete run.
+
+$ gh-upstream-watch --repos acme/widgets --packs-dir tests/fixtures/packs --notify none
+[2026-09-30 08:24] acme/widgets#388 Document the retry flag: REOPENED: claim it (https://github.com/acme/widgets/issues/388)
+[2026-09-30 08:24] acme/widgets#390 Widget spins forever on an empty config: ACCEPTED by @maint: comment /assign now (https://github.com/acme/widgets/issues/390)
+[2026-09-30 08:24] acme/widgets#390 Widget spins forever on an empty config: COMPETING PR #401 (by @monalisa) says Closes #390: check scope before /assign (https://github.com/acme/widgets/pull/401)
+[2026-09-30 08:24] acme/widgets#392 Add retry backoff: review: @maint APPROVED (https://github.com/acme/widgets/pull/392)
+[2026-09-30 08:24] acme/widgets#395 [Community] Weekly sync thread: 1 comment(s) naming you (https://github.com/acme/widgets/issues/395)
+[2026-09-30 08:24] acme/widgets: someone requested your review: Tighten lint config (https://github.com/acme/widgets/pull/14)
+```
+
+The same two runs are a golden test (`tests/test_run.py`).
+
+## Install
+
+Requires the [GitHub CLI](https://cli.github.com) (`gh auth login` done) and Python 3.9 or newer.
+No other dependencies.
+
+```sh
+uv tool install gh-upstream-watch
+# or
+pipx install gh-upstream-watch
+# or, as a gh extension (runs from a checkout with your python3):
+gh extension install colinmcnamara/gh-upstream-watch    # then: gh upstream-watch --help
+```
+
+## Use
+
+```sh
+gh-upstream-watch init --repos acme/widgets       # writes ~/.config/gh-upstream-watch/config.json
+gh-upstream-watch --dry-run                       # one pass, print only, save nothing
+gh-upstream-watch                                 # one pass: alerts, then save state
+gh-upstream-watch status                          # what the state file knows
+```
+
+Each invocation is one pass. Schedule it; the tool prints a ready scheduler entry that points at
+the interpreter and script you ran it with:
+
+```sh
+gh-upstream-watch --print-plist   > ~/Library/LaunchAgents/local.gh-upstream-watch.plist   # macOS
+gh-upstream-watch --print-systemd                                                          # Linux
+gh-upstream-watch --print-cron
+```
+
+What one pass checks:
+
+- every open issue and PR in `repos` you are involved in (author, assignee, commenter, mentioned),
+  those closed in the last 14 days, `extras` (`owner/repo#n`), and anything already watched that
+  is still open. The saved state of a closed item is kept for `baseline_days` (90) after it was
+  last checked, so a reopen within that time alerts; after that it counts as new and seeds quietly;
+- unread GitHub notifications that mention you, request your review, or assign you, in the watched
+  repos (exact names; set `notification_repos` to `["*"]` for every repo, or to globs). This needs a
+  token with the `notifications` scope: `gh auth refresh -s notifications` if they come back 403;
+- claim boards defined by a pack (a pinned issue that lists claimable tasks), for `claim_groups`.
+
+Exit status: 0 when every check completed, 1 when something was unknown this run (logged as
+`unknown this run`; `gh` missing or signed out also lands here, with the fix printed), 2 for a
+config, argument or rule-pack error (including no repos configured), 3 when another run holds the
+state lock. `status` is a doctor: it checks `gh` and your login, shows the config path, the packs
+applied to each repo, the last complete run, and what the last run could not check.
+
+## Configuration
+
+JSON, at `$XDG_CONFIG_HOME/gh-upstream-watch/config.json` (default `~/.config/...`). Precedence:
+command line, then environment (`GH_UPSTREAM_WATCH_CONFIG`, `GH_UPSTREAM_WATCH_REPOS` comma list,
+`GH_UPSTREAM_WATCH_STATE`), then the file. Unknown keys are errors.
+
+```json
+{
+  "repos": ["acme/widgets", "acme/gadgets"],
+  "extras": ["octo-org/octo-repo#12"],
+  "notify": "auto",
+  "webhook": null,
+  "hook": null,
+  "packs_dirs": [],
+  "claim_groups": [],
+  "recent_closed_days": 14,
+  "retention_days": 30,
+  "baseline_days": 90,
+  "notification_repos": null,
+  "login": "octocat",
+  "bots": [],
+  "slack": {"enabled": false}
+}
+```
+
+Notifications: stdout always (text with the URL, or `--json` for JSON lines). `notify: auto` uses
+`$GH_UPSTREAM_WATCH_NOTIFY` (a command that gets the alert JSON on stdin) if set, else
+`terminal-notifier`, `notify-send`, or `osascript` (macOS; the URL is kept in the visible text,
+since those banners cannot open a link; the text is passed as arguments, never as script).
+`--webhook URL` also POSTs `{"text": ..., "alert": ...}`; it must be https (http only to
+localhost), and only a 2xx answer counts; a redirect is a failure and is not followed. Each alert is delivered to each destination separately; a destination that fails
+stays in the outbox and is retried on later runs (up to 5), without printing the alert again.
+Only `https://github.com/` links (and `https://*.slack.com/` for Slack) are passed to a notifier
+to open; a link from comment text that points elsewhere is replaced by the item's own URL.
+
+## Rule packs
+
+Packs are local JSON data, loaded from the bundled `packs/`, then
+`~/.config/gh-upstream-watch/packs/`, then any `--packs-dir`. A pack with the same `id` replaces
+an earlier one. Packs are never read from a watched repository: the repo you are watching must not
+be able to decide what you are told. Bundled: `generic` (wording for every repo) and
+`vllm-semantic-router` (the `/accept` then `/assign` flow of `vllm-project/semantic-router`).
+
+```json
+{
+  "id": "acme",
+  "repos": ["acme/*"],
+  "gates": [{
+    "id": "accept",
+    "comment": "^/accept\\b",
+    "authorized_by": {"associations": ["MEMBER", "OWNER"], "logins": []},
+    "then": "^/assign\\b",
+    "alert": "ACCEPTED by @{actor}: comment /assign now",
+    "alert_done": "ACCEPTED by @{actor}"
+  }],
+  "label_transitions": [{"id": "stuck", "assigned_to_me": true, "has": ["accepted"], "lacks": ["in-progress"],
+                         "alert": "in-progress label missing"}],
+  "quiet_titles": ["^\\[Community\\]"],
+  "messages": {"reopened": "REOPENED: claim it",
+               "competing_pr": "COMPETING PR #{number} (by @{author}) says Closes #{target}: check scope"}
+}
+```
+
+A gate matches only at the start of a comment (not a quoted line further down). If a gate lists
+`logins`, only those logins count. Otherwise only its `associations` count, `OWNER` and
+`COLLABORATOR` by default; `MEMBER` is not a default because an organization member can have
+read-only access. Author association alone cannot prove who may run a gate, so add the
+maintainers' logins to your copy of a pack when you know them. On first sight of an item, gates
+are checked too: an `/accept` already waiting alerts once. `then` is your own follow-up command; once you have posted it the alert drops the
+call to action. See `CONTRIBUTING.md` for the full schema and how to add a pack with a fixture.
+
+For anything a pack cannot express, `--hook /abs/path` runs your program once per
+watched item that has a previous fingerprint (no shell, 30 s timeout) with `{"key", "repo", "number", "me", "old", "new"}` on
+stdin; each stdout line `{"message": "...", "kind": "...", "url": "..."}` becomes an alert.
+
+## Reliability
+
+- Full pagination for search, comments, reviews, timeline and notifications. A search over
+  GitHub's 1,000-result cap is reported as unknown with a warning (no partitioning yet).
+- One failing item never loses the run; the state file is always saved.
+- The first run is silent, and the "seeded" flag is set only after a run in which every check
+  succeeded, so a half-failed first run cannot flood you later.
+- State writes are atomic (temp file, fsync, rename) under an exclusive lock. A corrupt state file
+  is moved aside and the next run re-seeds quietly.
+- Alerts are written to an outbox in the state file before delivery; a crash in between
+  re-delivers them on the next run (at least once; a duplicate is possible, a loss is not).
+- The state file is written mode 0600 (it holds titles and URLs from private repos).
+- Seen-id stores are pruned after `retention_days`, only after a complete pass, and never for an
+  id GitHub still returns.
+
+Known limits: polling cannot see an event GitHub never exposes, or a state that changes twice
+between polls. Notification asks use GitHub's `participating` filter, so an ask GitHub does not
+count as participating is not seen there (the issue and PR checks still run).
+
+## Trust
+
+The tool only reads GitHub. Three things you configure are trusted local code or endpoints:
+`--hook` runs a program with your permissions, `$GH_UPSTREAM_WATCH_NOTIFY` runs a command, and
+`--webhook` sends every alert (titles, logins, URLs) to that URL. Rule packs are data, but only
+load packs you have read. A failing hook makes that item unknown for the run, so nothing is lost.
+
+## Slack (optional, off by default)
+
+`--slack` (or `"slack": {"enabled": true}`) adds Slack mentions and replies in your threads. Read
+this before enabling it:
+
+- It needs [Claude Code](https://docs.anthropic.com/en/docs/claude-code) and the official Slack
+  plugin, already signed in. Each check is one headless `claude -p` call with a small model
+  (`haiku` by default), no built-in tools (`--tools ""`), only the Slack search and read-thread
+  tools allowed, no user or project settings, an empty temporary working directory, and a minimal
+  environment (no `GH_TOKEN`). That call costs money or plan usage; `every_minutes` (default 25)
+  throttles it.
+- Model output is untrusted. The answer must be exactly a JSON array. Each item must carry a
+  Slack channel id, a message ts and the text, plus proof: the raw `<@you>` tag for a mention, or
+  the ts of your own message for a thread reply. Items without proof, outside `channels` (when
+  set), or older than `days` are dropped. Be clear about what that proves: the proof fields are
+  themselves model output, so a prompt injection in a Slack message can forge them. The damage is
+  limited because the model has no tools except two Slack read tools, and only
+  `https://*.slack.com/` links are ever passed to a notifier.
+- Slack failures are counted in their own state (`status` shows them) and never make the GitHub
+  pass incomplete or block it.
+- Nothing is shipped: `user`, `query` and `channels` come from your config. The query is a prompt
+  with `{user}` and `{days}` placeholders; it must tell the model to output the fields above:
+
+```json
+"slack": {
+  "enabled": true,
+  "user": "UEXAMPLE1",
+  "days": 14,
+  "every_minutes": 25,
+  "channels": [],
+  "query": "You are a read-only Slack checker for user {user}. Search for messages from the last {days} days that mention <@{user}>, and replies to threads {user} posted in. Output ONLY a JSON array; each element: {{\"channel\": \"#name\", \"channel_id\": \"C...\", \"ts\": \"...\", \"author\": \"...\", \"kind\": \"mention\" or \"thread_reply\", \"your_ts\": \"ts of {user}'s own message in the thread, else empty\", \"evidence\": \"the raw mention text, e.g. <@{user}|name>, else empty\", \"text\": \"first 120 characters\", \"link\": \"permalink or empty\"}}. If there is nothing, output []."
+}
+```
+
+## Migrating from the single-file script
+
+`gh-upstream-watch migrate --from OLD_STATE.json --state NEW_STATE.json --claim-repo owner/repo`
+converts a v0 state file (one flat dict of fingerprints plus `_notifications`, `_slack`,
+`_claimable`). Fingerprints and seen ids are kept, so nothing re-alerts and nothing re-seeds.
+
+## License
+
+MIT. See `LICENSE`.

gh_upstream_watch-0.1.0/pyproject.toml

@@ -0,0 +1,44 @@
+[build-system]
+requires = ["uv_build>=0.10,<0.11"]
+build-backend = "uv_build"
+
+[project]
+name = "gh-upstream-watch"
+version = "0.1.0"
+description = "Read-only alerts for your upstream work: tells you the next action when a maintainer gate, a competing PR, or a review moves."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.9"
+authors = [{ name = "Colin McNamara", email = "colin@2cups.com" }]
+dependencies = []
+keywords = ["github", "gh-extension", "open-source", "notifications", "maintainers"]
+classifiers = [
+  "Environment :: Console",
+  "Operating System :: MacOS",
+  "Operating System :: POSIX :: Linux",
+  "Programming Language :: Python :: 3",
+  "Topic :: Software Development :: Version Control :: Git",
+]
+
+[project.urls]
+Homepage = "https://github.com/colinmcnamara/gh-upstream-watch"
+Issues = "https://github.com/colinmcnamara/gh-upstream-watch/issues"
+Changelog = "https://github.com/colinmcnamara/gh-upstream-watch/blob/main/CHANGELOG.md"
+
+[project.scripts]
+gh-upstream-watch = "gh_upstream_watch.cli:main"
+
+[dependency-groups]
+dev = ["pytest", "ruff"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+target-version = "py39"
+line-length = 150
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "B", "UP"]
+ignore = ["B904"]

gh_upstream_watch-0.1.0/src/gh_upstream_watch/__init__.py

@@ -0,0 +1,3 @@
+"""gh-upstream-watch: read-only alerts for your upstream work."""
+
+__version__ = "0.1.0"