feat: serve the latest Slackware -current ChangeLog entry to HomepageHEADmaster

Homepage's customapi widget speaks JSON and cannot parse text, so the
ChangeLog needs something in front of it. This proxy fetches the file,
keeps only the entry above the first separator, and serves the counts,
the CVE ids, a truncated package list and the entry as a page.

Package lines are matched by starting at column 0 rather than by their
trailing period, since the indented notes below them frequently end in
one too.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0184D3xBAHPcZE9jZ45R5J26

1 files changed, 88 insertions, 0 deletions

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..4a13a10
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,88 @@
+# slackware-changelog
+
+A widget for a [Homepage](https://gethomepage.dev) dashboard, one of the
+modules under `homepage-modules/`. Siblings share the shape described below.
+
+## Shape of a module
+
+Homepage's `customapi` widget fetches JSON and maps fields to labels. It
+cannot parse text, cannot do arithmetic, and refetches on every refresh
+interval. So each module is a small stdlib Python HTTP service on localhost
+that does the parsing and caching, plus:
+
+- `<name>.py` - the service, single file, stdlib only, executable
+- `test_<name>.py` - self-check, fakes the upstream, prints `ok`
+- `<name>.service` - systemd unit, `DynamicUser=yes`, config via `Environment=`
+- `homepage-services.yaml` / `homepage-settings.yaml` - snippets to merge
+
+No dependencies. No framework. `ThreadingHTTPServer` and `urllib`.
+
+## This module
+
+Serves the latest Slackware -current ChangeLog entry on `127.0.0.1:8098`.
+
+Endpoints: `/latest` (counts and summary), `/top` (the first `TOP_N` packages
+as flat fields), `/packages` (every package with its action), `/entry` (HTML
+page of the entry), `/refresh` (bypass the cache).
+
+### Why /top exists
+
+`customapi` maps a fixed list of field names to labels. It cannot iterate an
+array and cannot scroll, so a JSON list of packages renders as nothing. `/top`
+flattens the first `TOP_N` into `pkg1`, `pkg2`, ... which the widget can map
+one per row, and appends a `... and N more` row in the next slot when the entry
+is longer. The card links to the ChangeLog for the rest.
+
+Mapping more `pkgN` fields than the entry has packages is harmless: Homepage
+skips a field that is absent. So the snippet maps a fixed 9 rows regardless of
+how many that day's entry holds.
+
+### ChangeLog format
+
+The file is reverse-chronological. Entries are separated by a `+--------+`
+line, so the latest entry is everything before the first separator.
+
+Inside an entry:
+
+```
+Mon Sep  7 22:56:39 UTC 2026
+a/util-linux-2.42.3-x86_64-1.txz:  Upgraded.
+  This update fixes bugs and security issues.
+  (* Security fix *)
+l/cryptopp-8.9.0-x86_64-3.txz:  Rebuilt.
+  Fixed library location. Thanks to Petri Kaukasoina.
+```
+
+Gotcha: a package line is identified by **starting at column 0**, not by
+ending in a period. Note lines are indented and frequently end in a period
+too ("Thanks to Petri Kaukasoina."), so a period-based regex counts prose as
+packages. The test asserts this specific case.
+
+Actions seen: `Upgraded`, `Rebuilt`, `Added`, `Removed`. The parser counts
+whatever word it finds rather than matching a fixed list, so a new action
+verb shows up in `summary` instead of vanishing.
+
+Security fixes are marked by the literal `(* Security fix *)` on its own
+indented line. CVE ids appear in the notes as cve.org URLs.
+
+### Caching
+
+`CACHE_TTL` (default 1800s) governs upstream fetches; the widget's
+`refreshInterval` only redraws. A failed refresh keeps the previous entry and
+adds a `stale` field with the error, so an unreachable mirror degrades to an
+old entry rather than a blank card. `/refresh` forces a fetch but obeys the
+same fallback.
+
+### Rendering
+
+`/entry` escapes everything from the ChangeLog with `html.escape` before it
+reaches the page. Upstream text is not trusted markup; the test asserts no
+`<script` survives.
+
+## Conventions
+
+- GPLv2 only. Header notice in every source file.
+- Snippet YAML files are merged into Homepage's config by hand, never copied
+  over it; the comments at the top of each say so.
+- Layout groups: any group omitted from `layout:` falls to the bottom of the
+  page, so the snippet reminds the reader to list their existing groups too.