argus-herald 0.2.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- argus_herald-0.2.0/.env.example +49 -0
- argus_herald-0.2.0/.gitignore +15 -0
- argus_herald-0.2.0/LICENSE +21 -0
- argus_herald-0.2.0/PKG-INFO +478 -0
- argus_herald-0.2.0/README.md +446 -0
- argus_herald-0.2.0/config.example.yaml +79 -0
- argus_herald-0.2.0/contrib/install-user-services.sh +42 -0
- argus_herald-0.2.0/contrib/systemd/argus-herald-ui.service +15 -0
- argus_herald-0.2.0/contrib/systemd/argus-herald-watch.service +16 -0
- argus_herald-0.2.0/examples/dragonhound.yaml +79 -0
- argus_herald-0.2.0/pyproject.toml +76 -0
- argus_herald-0.2.0/src/argus_herald/__init__.py +16 -0
- argus_herald-0.2.0/src/argus_herald/__main__.py +4 -0
- argus_herald-0.2.0/src/argus_herald/_version.py +24 -0
- argus_herald-0.2.0/src/argus_herald/charts.py +256 -0
- argus_herald-0.2.0/src/argus_herald/cli.py +1396 -0
- argus_herald-0.2.0/src/argus_herald/config.py +559 -0
- argus_herald-0.2.0/src/argus_herald/dashboard.py +580 -0
- argus_herald-0.2.0/src/argus_herald/digest.py +556 -0
- argus_herald-0.2.0/src/argus_herald/discover.py +138 -0
- argus_herald-0.2.0/src/argus_herald/drafting.py +334 -0
- argus_herald-0.2.0/src/argus_herald/engagement.py +474 -0
- argus_herald-0.2.0/src/argus_herald/feeds.py +97 -0
- argus_herald-0.2.0/src/argus_herald/github.py +143 -0
- argus_herald-0.2.0/src/argus_herald/http.py +108 -0
- argus_herald-0.2.0/src/argus_herald/legacy.py +64 -0
- argus_herald-0.2.0/src/argus_herald/media.py +297 -0
- argus_herald-0.2.0/src/argus_herald/metrics.py +553 -0
- argus_herald-0.2.0/src/argus_herald/models.py +94 -0
- argus_herald-0.2.0/src/argus_herald/notes.py +70 -0
- argus_herald-0.2.0/src/argus_herald/oauth1.py +75 -0
- argus_herald-0.2.0/src/argus_herald/platforms/__init__.py +380 -0
- argus_herald-0.2.0/src/argus_herald/privacy.py +258 -0
- argus_herald-0.2.0/src/argus_herald/py.typed +0 -0
- argus_herald-0.2.0/src/argus_herald/pypi.py +113 -0
- argus_herald-0.2.0/src/argus_herald/schedule.py +195 -0
- argus_herald-0.2.0/src/argus_herald/store.py +672 -0
- argus_herald-0.2.0/src/argus_herald/textutil.py +117 -0
- argus_herald-0.2.0/src/argus_herald/ui/__init__.py +5 -0
- argus_herald-0.2.0/src/argus_herald/ui/app.py +977 -0
- argus_herald-0.2.0/src/argus_herald/ui/dashboard_view.py +246 -0
- argus_herald-0.2.0/src/argus_herald/ui/static/brand/apple-icon.png +0 -0
- argus_herald-0.2.0/src/argus_herald/ui/static/brand/favicon.ico +0 -0
- argus_herald-0.2.0/src/argus_herald/ui/static/brand/icon.svg +1 -0
- argus_herald-0.2.0/src/argus_herald/ui/static/dashboard.js +87 -0
- argus_herald-0.2.0/src/argus_herald/ui/static/review.css +459 -0
- argus_herald-0.2.0/src/argus_herald/ui/static/review.js +73 -0
- argus_herald-0.2.0/src/argus_herald/ui/templates/attach_list.html +15 -0
- argus_herald-0.2.0/src/argus_herald/ui/templates/base.html +52 -0
- argus_herald-0.2.0/src/argus_herald/ui/templates/broadcasts.html +56 -0
- argus_herald-0.2.0/src/argus_herald/ui/templates/compose.html +35 -0
- argus_herald-0.2.0/src/argus_herald/ui/templates/confirm_form.html +6 -0
- argus_herald-0.2.0/src/argus_herald/ui/templates/dashboard.html +162 -0
- argus_herald-0.2.0/src/argus_herald/ui/templates/digests.html +68 -0
- argus_herald-0.2.0/src/argus_herald/ui/templates/draft.html +244 -0
- argus_herald-0.2.0/src/argus_herald/ui/templates/login.html +17 -0
- argus_herald-0.2.0/src/argus_herald/ui/templates/missing.html +8 -0
- argus_herald-0.2.0/src/argus_herald/ui/templates/queue.html +46 -0
- argus_herald-0.2.0/src/argus_herald/workflow.py +843 -0
- argus_herald-0.2.0/src/pip_release/__init__.py +37 -0
- argus_herald-0.2.0/tests/bombadil/.gitignore +2 -0
- argus_herald-0.2.0/tests/bombadil/lib.ts +77 -0
- argus_herald-0.2.0/tests/bombadil/locked.spec.ts +51 -0
- argus_herald-0.2.0/tests/bombadil/package-lock.json +23 -0
- argus_herald-0.2.0/tests/bombadil/package.json +11 -0
- argus_herald-0.2.0/tests/bombadil/review.spec.ts +269 -0
- argus_herald-0.2.0/tests/bombadil/run.sh +59 -0
- argus_herald-0.2.0/tests/bombadil/serve.py +410 -0
- argus_herald-0.2.0/tests/conftest.py +21 -0
- argus_herald-0.2.0/tests/fixtures/gh_releases.atom +32 -0
- argus_herald-0.2.0/tests/fixtures/site_updates.xml +22 -0
- argus_herald-0.2.0/tests/fixtures/youtube.xml +16 -0
- argus_herald-0.2.0/tests/test_accounts.py +112 -0
- argus_herald-0.2.0/tests/test_audience.py +146 -0
- argus_herald-0.2.0/tests/test_broadcasts.py +118 -0
- argus_herald-0.2.0/tests/test_cli.py +179 -0
- argus_herald-0.2.0/tests/test_compose.py +166 -0
- argus_herald-0.2.0/tests/test_config_and_text.py +154 -0
- argus_herald-0.2.0/tests/test_dashboard.py +240 -0
- argus_herald-0.2.0/tests/test_digest.py +262 -0
- argus_herald-0.2.0/tests/test_discover.py +92 -0
- argus_herald-0.2.0/tests/test_drafting.py +188 -0
- argus_herald-0.2.0/tests/test_engagement.py +269 -0
- argus_herald-0.2.0/tests/test_github.py +226 -0
- argus_herald-0.2.0/tests/test_legacy.py +84 -0
- argus_herald-0.2.0/tests/test_media.py +141 -0
- argus_herald-0.2.0/tests/test_metrics.py +140 -0
- argus_herald-0.2.0/tests/test_oauth1.py +37 -0
- argus_herald-0.2.0/tests/test_privacy.py +117 -0
- argus_herald-0.2.0/tests/test_schedule.py +138 -0
- argus_herald-0.2.0/tests/test_ui.py +552 -0
- argus_herald-0.2.0/tests/test_workflow.py +383 -0
|
@@ -0,0 +1,49 @@
|
|
|
1
|
+
# X (Twitter) OAuth 1.0a user tokens. Only needed with destinations.twitter.mode: api;
|
|
2
|
+
# the default manual mode posts through an Open in X link. A post that contains a URL is billed
|
|
3
|
+
# at the URL rate on the X developer console. Check the current price before
|
|
4
|
+
# approving those drafts.
|
|
5
|
+
X_API_KEY=
|
|
6
|
+
X_API_SECRET=
|
|
7
|
+
X_ACCESS_TOKEN=
|
|
8
|
+
X_ACCESS_TOKEN_SECRET=
|
|
9
|
+
|
|
10
|
+
# Discord incoming webhook for the announcement channel.
|
|
11
|
+
DISCORD_WEBHOOK_URL=
|
|
12
|
+
|
|
13
|
+
# Telegram bot that is an administrator of the announcement channel.
|
|
14
|
+
TELEGRAM_BOT_TOKEN=
|
|
15
|
+
TELEGRAM_CHAT_ID=
|
|
16
|
+
|
|
17
|
+
# Optional HTTPS endpoint that receives a JSON body when drafts are waiting.
|
|
18
|
+
# HTTP is accepted only for localhost.
|
|
19
|
+
ARGUS_HERALD_REVIEW_WEBHOOK=
|
|
20
|
+
|
|
21
|
+
# Review UI. Leave the token empty to open http://127.0.0.1:8787/ with no login.
|
|
22
|
+
# Docker listens beyond loopback inside the container, so the review service
|
|
23
|
+
# refuses to start until ARGUS_HERALD_UI_TOKEN is set. ARGUS_HERALD_UI_SECRET
|
|
24
|
+
# keeps you signed in across restarts.
|
|
25
|
+
ARGUS_HERALD_UI_TOKEN=
|
|
26
|
+
ARGUS_HERALD_UI_SECRET=
|
|
27
|
+
ARGUS_HERALD_UI_URL=http://127.0.0.1:8787
|
|
28
|
+
|
|
29
|
+
# Desktop notification when drafts are waiting. Set to 0 to stay quiet.
|
|
30
|
+
# Uses notify-send, so it appears in the GNOME notification list.
|
|
31
|
+
ARGUS_HERALD_DESKTOP_NOTIFY=1
|
|
32
|
+
|
|
33
|
+
# Optional. discover --check and collect use it for the rate limit; collect needs it for
|
|
34
|
+
# traffic (14-day retention) and star history. Fine-grained, limited to your repos:
|
|
35
|
+
# Metadata: read, Administration: read.
|
|
36
|
+
GITHUB_TOKEN=
|
|
37
|
+
|
|
38
|
+
# Optional: assisted drafting with a local model (drafting.backend: openai_compatible)
|
|
39
|
+
ARGUS_HERALD_LLM_BASE_URL=
|
|
40
|
+
ARGUS_HERALD_LLM_MODEL=
|
|
41
|
+
|
|
42
|
+
# Optional: YouTube subscriber counts for collect (a Data API key; read-only public data)
|
|
43
|
+
YOUTUBE_API_KEY=
|
|
44
|
+
|
|
45
|
+
# Optional: site traffic for collect, from Cloudflare Web Analytics (GraphQL Analytics API).
|
|
46
|
+
# Token permission: Account Analytics: read. The site tag is in the Web Analytics snippet.
|
|
47
|
+
CF_API_TOKEN=
|
|
48
|
+
CF_ACCOUNT_ID=
|
|
49
|
+
CF_SITE_TAG=
|
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
.venv/
|
|
2
|
+
__pycache__/
|
|
3
|
+
*.py[cod]
|
|
4
|
+
.pytest_cache/
|
|
5
|
+
.ruff_cache/
|
|
6
|
+
*.egg-info/
|
|
7
|
+
dist/
|
|
8
|
+
build/
|
|
9
|
+
.env
|
|
10
|
+
config.yaml
|
|
11
|
+
.argus-herald/
|
|
12
|
+
# The data directory before the rename; moved to .argus-herald/ on first run.
|
|
13
|
+
.pip-release/
|
|
14
|
+
# hatch-vcs writes this at build time (version derived from git tags)
|
|
15
|
+
src/argus_herald/_version.py
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 smk762
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,478 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: argus-herald
|
|
3
|
+
Version: 0.2.0
|
|
4
|
+
Summary: Release announcements for any Python package: drafted from PyPI and GitHub, held for review, published to your channels.
|
|
5
|
+
Project-URL: Repository, https://github.com/smk762/argus-herald
|
|
6
|
+
Author: smk762
|
|
7
|
+
License-Expression: MIT
|
|
8
|
+
License-File: LICENSE
|
|
9
|
+
Classifier: Development Status :: 3 - Alpha
|
|
10
|
+
Classifier: Intended Audience :: Developers
|
|
11
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
12
|
+
Classifier: Programming Language :: Python :: 3
|
|
13
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
14
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
15
|
+
Classifier: Topic :: Software Development :: Build Tools
|
|
16
|
+
Classifier: Typing :: Typed
|
|
17
|
+
Requires-Python: >=3.11
|
|
18
|
+
Requires-Dist: itsdangerous>=2
|
|
19
|
+
Requires-Dist: jinja2>=3.1
|
|
20
|
+
Requires-Dist: pillow>=10
|
|
21
|
+
Requires-Dist: python-multipart>=0.0.9
|
|
22
|
+
Requires-Dist: pyyaml>=6
|
|
23
|
+
Requires-Dist: starlette>=0.41
|
|
24
|
+
Requires-Dist: uvicorn>=0.32
|
|
25
|
+
Provides-Extra: claude
|
|
26
|
+
Requires-Dist: anthropic>=2.8; extra == 'claude'
|
|
27
|
+
Provides-Extra: dev
|
|
28
|
+
Requires-Dist: httpx>=0.27; extra == 'dev'
|
|
29
|
+
Requires-Dist: pytest>=8; extra == 'dev'
|
|
30
|
+
Requires-Dist: ruff==0.15.16; extra == 'dev'
|
|
31
|
+
Description-Content-Type: text/markdown
|
|
32
|
+
|
|
33
|
+
<h1>
|
|
34
|
+
<picture>
|
|
35
|
+
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/smk762/argus-cortex/dev/brand/packages/herald/argus-herald-lockup-dark.svg">
|
|
36
|
+
<img alt="argus-herald" src="https://raw.githubusercontent.com/smk762/argus-cortex/dev/brand/packages/herald/argus-herald-lockup-light.svg" height="52">
|
|
37
|
+
</picture>
|
|
38
|
+
</h1>
|
|
39
|
+
|
|
40
|
+
[](https://github.com/smk762/argus-herald/actions/workflows/ci.yml)
|
|
41
|
+
[](https://pypi.org/project/argus-herald/)
|
|
42
|
+
[](https://pypi.org/project/argus-herald/)
|
|
43
|
+
[](LICENSE)
|
|
44
|
+
|
|
45
|
+
The [Argus suite](https://docs.dragonhound.dev)'s release broadcaster, and one any maintainer can run for their own packages. argus-herald watches PyPI projects, drafts an announcement for each new version, and waits for a person to edit and approve it before anything is published. Posts that aren't releases (demos, build notes, videos) go through the same queue.
|
|
46
|
+
|
|
47
|
+
Public identities live in YAML or JSON. Tokens and webhook URLs live in `.env`. The first poll records versions that are already on PyPI and does not draft them. Later versions become one draft per enabled platform.
|
|
48
|
+
|
|
49
|
+
Discord and Telegram publish through their APIs. X and Patreon are handed to a person: an approved X draft becomes an **Open in X** link with the text filled in (no API call, so no per-post charge, and media can be attached by hand), and an approved Patreon draft is printed for the creator's editor, because Patreon's public API does not create posts. After posting, `argus-herald confirm <id> --url <post url>` marks the draft published and keeps the URL for analytics.
|
|
50
|
+
|
|
51
|
+
## Upgrading from pip-release
|
|
52
|
+
|
|
53
|
+
This project used to be called pip-release. Until 0.3 the old names keep working and log a warning that names the new one:
|
|
54
|
+
|
|
55
|
+
| Before | Now |
|
|
56
|
+
|---|---|
|
|
57
|
+
| `pip-release` command | `argus-herald` |
|
|
58
|
+
| `PIP_RELEASE_*` variables | `ARGUS_HERALD_*` (the new name wins when both are set) |
|
|
59
|
+
| `.pip-release/` data directory | `.argus-herald/`, moved on first run unless `store.path` names the old one |
|
|
60
|
+
| `~/.config/pip-release/opsec-denylist.txt` | `~/.config/argus-herald/opsec-denylist.txt` (the old file is read until you move it) |
|
|
61
|
+
| `pip-release-watch` / `pip-release-ui` user services | `argus-herald-watch` / `argus-herald-ui`: rerun `contrib/install-user-services.sh` |
|
|
62
|
+
| `pip_release.platforms` entry points, `import pip_release` | `argus_herald.platforms`, `import argus_herald` |
|
|
63
|
+
|
|
64
|
+
The review UI's session cookie changed name too, so you sign in once more. Docker compose keeps using the volume it created under the old project name.
|
|
65
|
+
|
|
66
|
+
## Setup
|
|
67
|
+
|
|
68
|
+
```bash
|
|
69
|
+
pip install argus-herald # or: uv tool install argus-herald
|
|
70
|
+
argus-herald init
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
From a checkout, `make install` creates `.venv` with the test extras (it needs [uv](https://docs.astral.sh/uv/)). `make test` and `make lint` run what CI runs. `argus-herald init --example dragonhound` starts from the suite's own config instead of a blank one.
|
|
74
|
+
|
|
75
|
+
`init --example dragonhound` copies `examples/dragonhound.yaml` to `config.yaml` and `.env.example` to `.env`. That fixture tracks [dragonhound_dev](https://pypi.org/user/dragonhound_dev/) and names [dragonhound3](https://x.com/dragonhound3) and [AtlasRealms](https://www.patreon.com/c/AtlasRealms). Discord and Telegram are present and disabled until a channel exists. For any other maintainer, run `argus-herald init` and edit `config.yaml`.
|
|
76
|
+
|
|
77
|
+
PyPI documents per-project RSS, not a feed of one user's projects, and the profile page often answers with a client challenge. `argus-herald discover` prints project names when the profile is readable. Otherwise keep the explicit `pypi.projects` list.
|
|
78
|
+
|
|
79
|
+
`argus-herald discover --check` looks for drift and exits 1 when it finds any, so it can run in CI. The watcher also runs it once a day and raises a desktop notice. It checks that:
|
|
80
|
+
|
|
81
|
+
- every configured name exists on PyPI;
|
|
82
|
+
- the PyPI profile, when it's readable, lists nothing that isn't configured;
|
|
83
|
+
- every public, non-fork repo of `pypi.discover.github_owner` whose name starts with `pypi.discover.prefix` and declares a `[project] name` in its `pyproject.toml` that is on PyPI is configured. PyPI can't list projects by prefix, so GitHub is how new packages are found.
|
|
84
|
+
|
|
85
|
+
```yaml
|
|
86
|
+
pypi:
|
|
87
|
+
projects: [argus-atlas, …]
|
|
88
|
+
discover:
|
|
89
|
+
github_owner: smk762
|
|
90
|
+
prefix: argus-
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
`GITHUB_TOKEN` is optional and only raises the API rate limit. A project added to `pypi.projects` is baselined on the next poll (or right away with `argus-herald baseline <name>`), so its old versions are never drafted.
|
|
94
|
+
|
|
95
|
+
## Review
|
|
96
|
+
|
|
97
|
+
Open the queue in a browser:
|
|
98
|
+
|
|
99
|
+
```bash
|
|
100
|
+
argus-herald ui
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
That listens on `http://127.0.0.1:8787/`. Drafts are grouped by release. You can edit the text, approve or reject it, and publish from the same page. Saving an edit puts the draft back to pending. For X, Publish shows **Open in X** and **Copy text**. For Patreon, it shows the title and HTML to paste. After posting, paste the post's URL and press “I published this on …”. A post confirmed without a URL can have one added later from the same page.
|
|
104
|
+
|
|
105
|
+
Set `ARGUS_HERALD_UI_TOKEN` when the UI is reachable beyond your own machine. Docker’s review service listens inside the container on all interfaces and publishes only `127.0.0.1:8787` on the host, so it requires that token. `ARGUS_HERALD_UI_URL` is included in the optional review webhook and printed after `poll` when new drafts appear.
|
|
106
|
+
|
|
107
|
+
The same actions are available from the shell:
|
|
108
|
+
|
|
109
|
+
```bash
|
|
110
|
+
argus-herald poll # baseline, or draft what is new
|
|
111
|
+
argus-herald drafts
|
|
112
|
+
argus-herald show 1
|
|
113
|
+
argus-herald edit 1 # $EDITOR; the draft returns to pending
|
|
114
|
+
argus-herald approve 1
|
|
115
|
+
argus-herald publish 1
|
|
116
|
+
argus-herald publish --approved --dry-run
|
|
117
|
+
argus-herald confirm 1 --url https://x.com/<user>/status/<id> # after a manual post
|
|
118
|
+
argus-herald baseline # mark every current version seen, without drafting
|
|
119
|
+
argus-herald reset --reject-pending [--before 2026-11-15] [--yes]
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
`baseline` does what the first poll does, on demand and for projects that are already tracked: every version on PyPI right now is marked seen, so the next `poll` drafts only what is released after it. `reset --reject-pending` rejects pending drafts with the note `stale backlog`. It shows the count per project and asks first unless `--yes` is given. Together they clear a backlog of old releases nobody wants announced.
|
|
123
|
+
|
|
124
|
+
`argus-herald watch` repeats `poll` on `poll.interval_seconds` (at least 60, default 1800). A new draft can also be posted as JSON to `ARGUS_HERALD_REVIEW_WEBHOOK`. When `notify-send` is available, the same event raises a desktop notification that stays in the GNOME notification list. Set `ARGUS_HERALD_DESKTOP_NOTIFY=0` to skip it. While any draft is still pending, that alert is repeated every 24 hours.
|
|
125
|
+
|
|
126
|
+
## GitHub Releases
|
|
127
|
+
|
|
128
|
+
Repos that ship without PyPI (a web UI, a demo) can still be announced. Their GitHub releases are a second source:
|
|
129
|
+
|
|
130
|
+
```yaml
|
|
131
|
+
github:
|
|
132
|
+
owner: smk762
|
|
133
|
+
prefix: argus- # every public, non-fork repo starting with this; or repos: [a, b]
|
|
134
|
+
include_prereleases: true # collected into digests, never drafted on their own
|
|
135
|
+
```
|
|
136
|
+
|
|
137
|
+
Each repo is baselined on its first read. With `GITHUB_TOKEN` the REST API is used. Without it, the public `releases.atom` feed is read, which never lists drafts. Tags must be versions (`v0.4.0` becomes `0.4.0`), so asset-only tags like `stock-heads` are skipped. A version released on both PyPI and GitHub is kept once, under PyPI, with the GitHub release notes, whichever was seen first. In a digest, GitHub-only releases are listed with `source: github`.
|
|
138
|
+
|
|
139
|
+
## Digests
|
|
140
|
+
|
|
141
|
+
A suite that releases often shouldn't post every version. With a `digest:` block, releases are collected into fixed windows instead of drafted one by one:
|
|
142
|
+
|
|
143
|
+
```yaml
|
|
144
|
+
digest:
|
|
145
|
+
anchor: 2026-11-16 # first day of the first window (UTC)
|
|
146
|
+
window_days: 14
|
|
147
|
+
site_url: https://dragonhound.dev/updates/
|
|
148
|
+
site_dir: /path/to/site/src/content/updates # local checkout; herald writes here, never commits
|
|
149
|
+
platforms: [] # default: every enabled destination
|
|
150
|
+
```
|
|
151
|
+
|
|
152
|
+
When a window closes (the watcher checks on every poll), herald creates one digest with every release seen before the close. A release seen after its window closed goes into the next one. For each digest it drafts:
|
|
153
|
+
|
|
154
|
+
- **a site page** `<close date>-digest.md` with front matter (`title`, `date`, `kind: digest`, `summary`, `period`, `releases` grouped by package, oldest version first) and `draft: true`, plus a short list of highlights for a person to rewrite into prose. The page passes the privacy gate first. Herald writes it only when no file is there, or when the file is still exactly what herald wrote, so your edits are never overwritten;
|
|
155
|
+
- **one post per destination**: the period, the count, up to three notable changes (as many as fit the platform without clipping), and the link to the page.
|
|
156
|
+
|
|
157
|
+
Each highlight is the first sentence of the release's first *Added* bullet, or of its first bullet, or its summary. A release is **suggested** for a headline post of its own when it's a major or minor bump, or a first release, and its notes add something. Patch releases and prereleases are never suggested. Suggestions are only badges: promoting is your call.
|
|
158
|
+
|
|
159
|
+
The **Digests** page in the review UI shows the open window and past digests. Drop a release from a digest, promote one to its own `headline` post (optionally with a `kind: release` site page), or **Rebuild** a digest after a change. Rebuild refreshes drafts nobody has edited, and the page if nobody has edited it. From the shell:
|
|
160
|
+
|
|
161
|
+
```bash
|
|
162
|
+
argus-herald digest # open window and recent digests
|
|
163
|
+
argus-herald digest exclude argus-lens==0.12.1
|
|
164
|
+
argus-herald digest rebuild 3
|
|
165
|
+
argus-herald promote argus-lens==0.13.0 --site-page
|
|
166
|
+
```
|
|
167
|
+
|
|
168
|
+
Without a `digest:` block (or with `mode: per_release`), every release gets its own drafts as before.
|
|
169
|
+
|
|
170
|
+
## Metrics
|
|
171
|
+
|
|
172
|
+
`argus-herald collect` snapshots adoption metrics into `metrics.sqlite`, next to the queue. They stay on this machine. The watcher runs it once a day. Every write is an upsert, so running it again does no harm.
|
|
173
|
+
|
|
174
|
+
| Table | From | Needs |
|
|
175
|
+
| --- | --- | --- |
|
|
176
|
+
| `gh_traffic` (daily views, uniques, clones) | GitHub traffic API | `GITHUB_TOKEN` |
|
|
177
|
+
| `gh_referrers`, `gh_paths` (snapshot per day) | GitHub traffic API | `GITHUB_TOKEN` |
|
|
178
|
+
| `gh_star_counts` (stars per repo per day) | GitHub repo list | nothing |
|
|
179
|
+
| `gh_stars` (when each star was given; the stargazer is stored only as a hash) | GitHub stargazers API | `GITHUB_TOKEN` |
|
|
180
|
+
| `pypi_downloads` (daily, without mirrors, last 180 days) | pypistats.org | nothing |
|
|
181
|
+
| `events` (release times, and published posts with their URL) | PyPI JSON API and the review queue | nothing |
|
|
182
|
+
|
|
183
|
+
Repos are the public, non-fork repos of `pypi.discover.github_owner` that start with `pypi.discover.prefix`. **GitHub keeps traffic for 14 days only**, so whatever isn't collected within that time is gone.
|
|
184
|
+
|
|
185
|
+
The traffic endpoints only answer to an account with write access to the repo. A fine-grained token limited to those repos, with **Metadata: read** and **Administration: read**, works for traffic. GitHub is limiting stargazer lists to admins and collaborators, and with such a token they answer 403. That is reported as skipped, not as an error, and `gh_star_counts` still tracks stars per day. `--since 2026-11-01` keeps only PyPI download days from that date.
|
|
186
|
+
|
|
187
|
+
### Dashboard
|
|
188
|
+
|
|
189
|
+
`/dashboard` in the review UI (same sign-in) asks one question of the metrics: do announcements move adoption, and which platform and format does it best? It reads `metrics.sqlite` on this machine and nothing leaves it unless you export a CSV. The charts are inline SVG, with no CDN, in light and dark.
|
|
190
|
+
|
|
191
|
+
- **Timeline:** PyPI downloads, GitHub views, unique visitors, clones, new stars and site visits on one shared time axis, each with a 7-day mean. Grey lines mark releases; coloured ones mark posts (hover for the text, click to open it). Linear or log scale, for the suite or one package.
|
|
192
|
+
- **Followers** per platform.
|
|
193
|
+
- **GitHub referrers:** unique visitors by source (X, Bluesky, Mastodon, Reddit, Hacker News, search, your own site, other), stacked.
|
|
194
|
+
- **Broadcasts:** one row per post, with engagement at 24h and 7d and the change in downloads, views, stars and that platform's referrers. The change compares the 72 hours from the post with the median day of the 14 days before. These are associations, not effects; rows whose window overlaps another post are greyed out. Sort by any column; filter by platform, format, media, drafting backend, or herald vs logged by hand.
|
|
195
|
+
- **Platforms by week:** posts, engagement, referrer uniques and follower change. Weeks start on the digest anchor's weekday (Monday by default); change it in the filters.
|
|
196
|
+
|
|
197
|
+
Every table has a CSV link with the page's filters applied.
|
|
198
|
+
|
|
199
|
+
### Followers
|
|
200
|
+
|
|
201
|
+
`collect` also records audience size per platform per day in `account_metrics`:
|
|
202
|
+
|
|
203
|
+
```yaml
|
|
204
|
+
accounts:
|
|
205
|
+
bluesky: dragonhound.dev # public profile API, no login
|
|
206
|
+
mastodon: "@name@instance.social" # public account lookup, no login
|
|
207
|
+
# youtube: UC… # defaults to sources.youtube; needs YOUTUBE_API_KEY
|
|
208
|
+
```
|
|
209
|
+
|
|
210
|
+
An account that doesn't exist yet is reported as skipped until it does. X has no free API for this, so enter its numbers by hand, for example from the analytics page each Sunday:
|
|
211
|
+
|
|
212
|
+
```bash
|
|
213
|
+
argus-herald import x-account --date 2026-11-22 --followers 196 --following 410 --posts 2580
|
|
214
|
+
argus-herald followers # latest count per platform, with the change over 7 days
|
|
215
|
+
```
|
|
216
|
+
|
|
217
|
+
### Engagement per post
|
|
218
|
+
|
|
219
|
+
Each Bluesky and Mastodon post in the broadcast list (published by herald, or logged by hand with its URL) is read from the public API at +1h, +24h, +72h and +7d after it went out. The samples go to `post_metrics` as a time series of likes, reposts, replies and quotes. The watcher checks once an hour, and fetches only posts that have reached a checkpoint. A post deleted since is reported as skipped.
|
|
220
|
+
|
|
221
|
+
X has no free API for this, so import the analytics export instead. Per-post exports are matched to herald's broadcasts by post id. Posts made outside herald are stored too. An account overview export (one row per day) goes to `account_engagement`. When only the week's totals are at hand, enter them:
|
|
222
|
+
|
|
223
|
+
```bash
|
|
224
|
+
argus-herald import x-analytics ~/Downloads/account_analytics_content.csv
|
|
225
|
+
argus-herald import x-analytics ~/Downloads/account_overview_analytics.csv
|
|
226
|
+
argus-herald import x-week --end 2026-11-29 --impressions 9000 --engagements 310 --link-clicks 40 --profile-visits 55 --new-follows 16
|
|
227
|
+
```
|
|
228
|
+
|
|
229
|
+
Importing the same post again adds a new sample, so a weekly import draws the curve for X as well. `slots suggest` uses this data.
|
|
230
|
+
|
|
231
|
+
### Site traffic
|
|
232
|
+
|
|
233
|
+
With Cloudflare Web Analytics on the site, `collect` keeps daily page views and visits per path (`site_traffic`) and per referring host (`site_referrers`) for the last 7 days on each run. Set `CF_API_TOKEN` (a token with Account Analytics: read), `CF_ACCOUNT_ID` and `CF_SITE_TAG` (from the Web Analytics site's snippet) in `.env`. `argus-herald platforms` lists which metrics sources are set up.
|
|
234
|
+
|
|
235
|
+
### Posts made outside herald
|
|
236
|
+
|
|
237
|
+
Some posts are always made by hand: Reddit, Hacker News, YouTube uploads, newsletter and link-roundup submissions. Log them so they appear on the metrics timeline next to herald's own posts:
|
|
238
|
+
|
|
239
|
+
```bash
|
|
240
|
+
argus-herald log-broadcast --platform reddit --url https://www.reddit.com/r/gis/comments/… --kind demo --project argus-atlas
|
|
241
|
+
argus-herald log-broadcast --platform hn --url "https://news.ycombinator.com/item?id=…" --at 2027-01-05T15:00Z
|
|
242
|
+
argus-herald broadcasts # list
|
|
243
|
+
argus-herald log-broadcast --id 3 --subject "Show HN: atlas" # edit
|
|
244
|
+
argus-herald broadcasts delete 3
|
|
245
|
+
```
|
|
246
|
+
|
|
247
|
+
`--platform` is any short name. `x` or `twitter` URLs are normalised like confirmed X posts. `--at` defaults to now, in UTC. The review UI has the same under **Logged posts**. Each `collect` rebuilds the broadcast events, so edits and deletions carry through.
|
|
248
|
+
|
|
249
|
+
## Assisted drafting
|
|
250
|
+
|
|
251
|
+
A model can write the first draft of each digest and headline post: it picks the changes that matter to each destination's audience and words them in its tone. A person still edits and approves every word.
|
|
252
|
+
|
|
253
|
+
```yaml
|
|
254
|
+
drafting:
|
|
255
|
+
backend: openai_compatible # template (default) | openai_compatible | anthropic
|
|
256
|
+
models: {headline: other-model} # optional, per task
|
|
257
|
+
```
|
|
258
|
+
|
|
259
|
+
- **`openai_compatible`** is a local server (Ollama's `/v1`, llama.cpp, vLLM), so draft inputs stay on your network. Put `ARGUS_HERALD_LLM_BASE_URL` (for example `http://<your-ollama-host>:11434/v1`; plain `http://` is accepted only for this machine or a private address) and `ARGUS_HERALD_LLM_MODEL` in `.env`, never in the committed config. `llama3.1:8b-instruct` did best in testing.
|
|
260
|
+
- **`anthropic`** uses Claude through the official SDK: `pip install 'argus-herald[claude]'`, with credentials from `ANTHROPIC_API_KEY` or `ant auth login`. The default model is `claude-opus-5-5` at `effort: low`, with the server-side refusal fallback on. The privacy gate scrubs everything sent (deny-list terms, emails, private addresses, paths). With no gate, nothing is sent.
|
|
261
|
+
|
|
262
|
+
The model writes only the text, and herald adds the link and hashtags. A model doesn't reliably follow rules, so herald checks them in code:
|
|
263
|
+
|
|
264
|
+
- no emoji (unless the audience sets `emoji: true`), no links or hashtags of its own;
|
|
265
|
+
- at most three items, and the post must fit the platform without clipping.
|
|
266
|
+
|
|
267
|
+
Emoji, and extra or overlong items at the end, are removed outright. Nothing is cut mid-sentence. Anything else gets one retry naming the broken rule, and after that the template draft is used, with a note on the draft saying why. Markdown backticks are removed, and reasoning output (`<think>…</think>`) is stripped.
|
|
268
|
+
|
|
269
|
+
Each draft records who wrote it ("Drafted by openai_compatible:llama3.1…"). **Regenerate** on a digest or headline draft writes it again, but only replaces your edits if you tick *replace my edits* (`argus-herald regenerate <id> [--force]`). Digest rebuilds and promotions use the model too.
|
|
270
|
+
|
|
271
|
+
## Posts that aren't releases
|
|
272
|
+
|
|
273
|
+
Demos, build notes, new pages and videos go through the same queue: one pending draft per destination, the privacy gate, approve, then publish or hand off.
|
|
274
|
+
|
|
275
|
+
```bash
|
|
276
|
+
argus-herald compose "Hex territories on real terrain." --kind demo --link https://example.org/realms
|
|
277
|
+
echo "How the curator scores a dataset." | argus-herald compose - --kind note --subject "Curator's numbers"
|
|
278
|
+
argus-herald approve --post post:3f2a… # every draft of one post
|
|
279
|
+
```
|
|
280
|
+
|
|
281
|
+
The review UI has the same form under **New post**. `--kind` is one of `demo`, `note`, `video`, `page`. Each platform's draft is fitted to its own limit and keeps the link.
|
|
282
|
+
|
|
283
|
+
Two feeds can create posts on their own. Each is baselined on its first read, like PyPI, so nothing already in it is announced:
|
|
284
|
+
|
|
285
|
+
```yaml
|
|
286
|
+
sources:
|
|
287
|
+
site:
|
|
288
|
+
feed: https://dragonhound.dev/updates.xml # Atom; entries whose category is listed become posts
|
|
289
|
+
categories: [note] # build notes ("digest" and "release" are also accepted)
|
|
290
|
+
platforms: [twitter] # default: every enabled destination
|
|
291
|
+
youtube:
|
|
292
|
+
channel_id: UCxZha6M0r90kFIGkFvKRvcw # a new video, Shorts included, becomes a post
|
|
293
|
+
platforms: [twitter]
|
|
294
|
+
```
|
|
295
|
+
|
|
296
|
+
Feeds are read on every `poll`, so the watcher picks them up too. Drafts from a feed are keyed by the item's id, so a feed entry is never drafted twice.
|
|
297
|
+
|
|
298
|
+
## Audiences
|
|
299
|
+
|
|
300
|
+
Each destination can describe who follows it and what they should get:
|
|
301
|
+
|
|
302
|
+
```yaml
|
|
303
|
+
destinations:
|
|
304
|
+
twitter:
|
|
305
|
+
audience:
|
|
306
|
+
description: Crypto and AI-image people
|
|
307
|
+
tone: plain and specific, visual first
|
|
308
|
+
hashtags: [gis] # appended while they fit; X takes at most 2
|
|
309
|
+
link_placement: reply # body (default) or reply
|
|
310
|
+
patreon:
|
|
311
|
+
audience:
|
|
312
|
+
packages: [argus-atlas, argus-realms] # or {include: [...], exclude: [...]}, globs allowed
|
|
313
|
+
```
|
|
314
|
+
|
|
315
|
+
- **Packages:** a destination only gets digests, headline posts and per-release drafts about packages it wants. A digest window with nothing for that audience produces no draft there, and a mixed digest is counted and summarised for that audience's packages only. Posts without a package, such as videos and build notes, go everywhere.
|
|
316
|
+
- **`link_placement: reply`:** keeps the post visual-first. The link moves into the draft's **Reply** field. On X, once you confirm the post's URL, herald offers **Open reply in X**, a reply intent under your post with the link filled in. Bluesky and Mastodon will post the reply themselves. Only those three can use `reply`.
|
|
317
|
+
- **`description` and `tone`:** shown on each draft for the reviewer, and passed to assisted drafting when that lands.
|
|
318
|
+
|
|
319
|
+
`argus-herald platforms` prints each audience.
|
|
320
|
+
|
|
321
|
+
## Scheduling
|
|
322
|
+
|
|
323
|
+
A destination with a schedule doesn't post the moment you approve. The draft waits for the next free slot:
|
|
324
|
+
|
|
325
|
+
```yaml
|
|
326
|
+
destinations:
|
|
327
|
+
twitter:
|
|
328
|
+
schedule:
|
|
329
|
+
slots: [Tue 08:00, Fri 08:00] # UTC
|
|
330
|
+
min_gap_hours: 24 # distance from this destination's other posts
|
|
331
|
+
offset_minutes: 0 # shift from the post's time on other platforms
|
|
332
|
+
grace_hours: 6
|
|
333
|
+
```
|
|
334
|
+
|
|
335
|
+
- On approve, a draft gets the next slot that's at least `min_gap_hours` from that destination's other scheduled or published posts. Drafts of the same post go out together: once one is scheduled, the others take its time plus their own `offset_minutes`.
|
|
336
|
+
- The watcher wakes up for each scheduled draft. API platforms post. X and Patreon are handed off with a desktop notice ("Time to post"), and the draft page has the Open/Copy buttons ready.
|
|
337
|
+
- If the watcher wasn't running and a slot passed more than `grace_hours` ago, nothing is posted late: you get a notice, and the draft stays approved without a time.
|
|
338
|
+
- Editing an approved draft returns it to pending and releases its slot.
|
|
339
|
+
- On the draft page, pick another free slot, enter a time, unschedule, or press **Publish** to post now. From the shell:
|
|
340
|
+
|
|
341
|
+
```bash
|
|
342
|
+
argus-herald approve 12 # also schedules it
|
|
343
|
+
argus-herald approve 12 --no-schedule # goes out when you publish it
|
|
344
|
+
argus-herald schedule 12 --at 2026-12-01T08:00Z # or --next, or --clear
|
|
345
|
+
argus-herald scheduled
|
|
346
|
+
argus-herald slots suggest # engagement by weekday and hour, once post metrics exist
|
|
347
|
+
```
|
|
348
|
+
|
|
349
|
+
`slots suggest` ranks weekday and time-of-day buckets per platform by engagement, and suggests a slot once a platform has at least 6 posts. It only suggests and never changes the config.
|
|
350
|
+
|
|
351
|
+
## Media
|
|
352
|
+
|
|
353
|
+
Any draft can carry images, GIFs or short clips, and each one needs alt text. On a draft's review page, upload a file or pick one from the media folder (`.argus-herald/media/` by default, or `media: {dir: …}`), and optionally attach it to every draft of the same post. From the shell:
|
|
354
|
+
|
|
355
|
+
```bash
|
|
356
|
+
argus-herald media add 12 ~/clips/atlas-coast.gif --alt "A coastline painted over real terrain, labels fading in" --all-drafts
|
|
357
|
+
argus-herald media list 12
|
|
358
|
+
argus-herald media alt 7 "Better description"
|
|
359
|
+
argus-herald compose "Coastlines, painted." --kind demo --media shot.png --alt "…"
|
|
360
|
+
```
|
|
361
|
+
|
|
362
|
+
**Metadata never leaves the machine.** Each file gets a cleaned copy, and only that copy is posted or handed off:
|
|
363
|
+
|
|
364
|
+
- **JPEG, PNG and WebP:** the EXIF rotation is applied, then EXIF (including GPS), XMP, IPTC, comments and text chunks are dropped. The colour profile is kept.
|
|
365
|
+
- **GIF:** frames and timing are kept, and comments are dropped.
|
|
366
|
+
- **MP4, MOV and WebM:** `ffmpeg -map_metadata -1 -c copy`. Without ffmpeg, a clip is attached but marked unstripped, and approve refuses it.
|
|
367
|
+
|
|
368
|
+
The review page says what was removed (for example "EXIF with GPS location, comment").
|
|
369
|
+
|
|
370
|
+
Approve is refused while any attachment lacks alt text, when the privacy gate flags alt text, or when the attachments don't fit the platform:
|
|
371
|
+
|
|
372
|
+
- **X:** 4 images, or 1 GIF or video; images up to 5 MB, GIFs up to 15 MB.
|
|
373
|
+
- **Patreon:** more generous limits.
|
|
374
|
+
- Platforms that can't attach media yet refuse drafts that carry it.
|
|
375
|
+
|
|
376
|
+
For X and Patreon, the handoff lists the cleaned files to download and attach, each with its alt text ready to copy.
|
|
377
|
+
|
|
378
|
+
## Privacy gate
|
|
379
|
+
|
|
380
|
+
Every draft passes a privacy gate on approve and again on publish. A hit refuses the draft; text is never rewritten. It catches:
|
|
381
|
+
|
|
382
|
+
- private and link-local IPs, home and mount paths, email addresses (except `example.*`, `*.invalid` and GitHub noreply), and LAN hostnames (`.lan`, `.local`, `.internal`, …);
|
|
383
|
+
- crypto addresses (EVM, Base58Check with a valid checksum, bech32, ENS names), except those in `privacy.allow_addresses`;
|
|
384
|
+
- timezone offsets attached to a timestamp, as in a pasted log or `git log` line (`+00:00` and `Z` are fine);
|
|
385
|
+
- any term in your private deny-list, and any regex in `privacy.patterns`.
|
|
386
|
+
|
|
387
|
+
The deny-list is a file outside the repository, one term per line, `#` comments allowed: `~/.config/argus-herald/opsec-denylist.txt` by default, or the path in `ARGUS_HERALD_OPSEC_DENYLIST`. Keep it `chmod 600`. If [ai-code-auditor](https://github.com/smk762/ai-code-auditor)'s list exists, its terms are enforced too. **Without the deny-list nothing can be approved or published.**
|
|
388
|
+
|
|
389
|
+
```yaml
|
|
390
|
+
privacy:
|
|
391
|
+
allow_addresses: ["0x…"] # public contracts that may appear in posts
|
|
392
|
+
patterns:
|
|
393
|
+
ticket: "INTERNAL-\\d+"
|
|
394
|
+
```
|
|
395
|
+
|
|
396
|
+
The review page highlights each hit. Edit the text, or accept one specific hit for that draft with a note saying why it is safe. From the shell:
|
|
397
|
+
|
|
398
|
+
```bash
|
|
399
|
+
argus-herald check # pending and approved drafts
|
|
400
|
+
argus-herald accept 12 'crypto-address:0x…' --note "public demo contract"
|
|
401
|
+
```
|
|
402
|
+
|
|
403
|
+
## Start at boot
|
|
404
|
+
|
|
405
|
+
On a machine with systemd, install user services for the watcher and the review UI:
|
|
406
|
+
|
|
407
|
+
```bash
|
|
408
|
+
contrib/install-user-services.sh
|
|
409
|
+
```
|
|
410
|
+
|
|
411
|
+
They start at login, and at boot as well when lingering is enabled for your user. The script tries `loginctl enable-linger`. The review page stays on `http://127.0.0.1:8787/`. Notifications are sent on the session bus, so they show up after you are logged into the desktop.
|
|
412
|
+
|
|
413
|
+
Exit status is 1 when a project could not be read. Drafts that fail to publish stay `failed` and can be published again.
|
|
414
|
+
|
|
415
|
+
## Platforms
|
|
416
|
+
|
|
417
|
+
| Id | Needs in `.env` | Publish |
|
|
418
|
+
| --- | --- | --- |
|
|
419
|
+
| `twitter` | none with `mode: manual` (default). With `mode: api`: `X_API_KEY`, `X_API_SECRET`, `X_ACCESS_TOKEN`, `X_ACCESS_TOKEN_SECRET` | Manual: an `https://x.com/intent/post?text=…` link for a person to post, then `argus-herald confirm <id> --url <post url>`. API: `POST https://api.x.com/2/tweets` with OAuth 1.0a; a post that includes a link is billed at the URL rate on the X developer console. Both modes cap posts at 280 weighted characters, and a URL counts as 23. |
|
|
420
|
+
| `discord` | `DISCORD_WEBHOOK_URL` | Incoming webhook. The edited text is the message, up to 2000 characters. |
|
|
421
|
+
| `telegram` | `TELEGRAM_BOT_TOKEN`, `TELEGRAM_CHAT_ID` | `sendMessage` as HTML. The bot must be allowed to post in the channel. |
|
|
422
|
+
| `patreon` | none | Prints title and HTML. `argus-herald confirm <id> [--url <post url>]` records that the creator published it. |
|
|
423
|
+
|
|
424
|
+
`argus-herald platforms` prints which destinations are enabled and which secret names are still empty. It does not print secret values.
|
|
425
|
+
|
|
426
|
+
Set `enabled: false` to keep a platform in the file without drafting for it. A platform omitted from `destinations` is not used. Unknown ids are an error.
|
|
427
|
+
|
|
428
|
+
## Add a platform
|
|
429
|
+
|
|
430
|
+
Implement the `Publisher` methods (`render`, `validate`, `missing_secrets`, `publish`) and register an entry point in group `argus_herald.platforms`. Then add a `destinations.<id>` block. Built-in publishers live in `src/argus_herald/platforms/__init__.py`.
|
|
431
|
+
|
|
432
|
+
Likely next publishers, in the order they are useful for a Python release: Mastodon, Bluesky, LinkedIn, Slack, Matrix, and an email or RSS handoff. Lemmy, Nostr, and Threads are further out. Mastodon and Bluesky already have maintained release actions elsewhere; this queue still has to own the PyPI poll and the approval step.
|
|
433
|
+
|
|
434
|
+
## Docker
|
|
435
|
+
|
|
436
|
+
Copy a config into place first (`argus-herald init --example dragonhound` or `cp config.example.yaml config.yaml`), then:
|
|
437
|
+
|
|
438
|
+
```bash
|
|
439
|
+
docker compose up -d --build
|
|
440
|
+
docker compose run --rm watcher drafts
|
|
441
|
+
```
|
|
442
|
+
|
|
443
|
+
The review service is on `http://127.0.0.1:8787/` after `ARGUS_HERALD_UI_TOKEN` is set in `.env`. The watcher runs as uid 10001 with a read-only root filesystem. Config is mounted read-only. The queue is the volume compose created before the rename, `pip-release_pip-release-data`, so existing drafts carry over. Release images are published as `ghcr.io/smk762/argus-herald`. Secrets come from `.env`.
|
|
444
|
+
|
|
445
|
+
## Tests
|
|
446
|
+
|
|
447
|
+
```bash
|
|
448
|
+
make test # pytest
|
|
449
|
+
make lint # ruff check and format --check, pinned to the suite's ruff
|
|
450
|
+
```
|
|
451
|
+
|
|
452
|
+
CI runs the suite's shared [`argus-ci`](https://github.com/smk762/argus-ci) workflow (ruff, pytest on Python 3.11 and 3.12, build) plus the Bombadil job below. Tooling comes from [`argus-pkg-template`](https://github.com/smk762/argus-pkg-template): `uvx copier update` pulls its changes.
|
|
453
|
+
|
|
454
|
+
### Releasing
|
|
455
|
+
|
|
456
|
+
The version comes from the git tag (`hatch-vcs`): tagging `vX.Y.Z` publishes the wheel to PyPI through trusted publishing and the image to GHCR. There is no version string to edit.
|
|
457
|
+
|
|
458
|
+
### UI properties (Bombadil)
|
|
459
|
+
|
|
460
|
+
[Bombadil](https://github.com/antithesishq/bombadil) explores the review UI on its own (clicks, typing, Back, jumps to any route, forms forced past disabled buttons) and checks properties in every state it reaches:
|
|
461
|
+
|
|
462
|
+
- Approve and Publish are never enabled for a draft with an unresolved privacy hit or an attachment without alt text, and no forced submission gets such a draft approved.
|
|
463
|
+
- Publish and scheduling appear only for approved drafts (Publish also retries a failed one); Open in X only once an X draft is handed off.
|
|
464
|
+
- Saving an edit returns the draft to pending.
|
|
465
|
+
- With `ARGUS_HERALD_UI_TOKEN` set, only the sign-in page is reachable, and it shows nothing from the queue.
|
|
466
|
+
- No 5xx, uncaught exceptions or console errors; WCAG AA text contrast; the chosen light or dark theme is the one shown.
|
|
467
|
+
|
|
468
|
+
```bash
|
|
469
|
+
cd tests/bombadil && npm install
|
|
470
|
+
CHROME=/path/to/chrome TIME_LIMIT=60s ./run.sh # light, dark and token-locked runs
|
|
471
|
+
npx bombadil browser inspect out/light # step through a run
|
|
472
|
+
```
|
|
473
|
+
|
|
474
|
+
`serve.py` starts the UI on a fresh temporary store with seeded drafts in every state, a fixture deny-list and fake publishers (nothing is posted), on a port the OS picks. CI runs both suites on every pull request.
|
|
475
|
+
|
|
476
|
+
## Licence
|
|
477
|
+
|
|
478
|
+
The code is MIT ([LICENSE](LICENSE)). The argus-herald mark, its favicons and the lockup are Argus brand assets from [argus-cortex `brand/`](https://github.com/smk762/argus-cortex/tree/dev/brand), not covered by the MIT licence: see [its terms](https://github.com/smk762/argus-cortex/blob/dev/brand/LICENSE).
|