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, 85 insertions, 0 deletions

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..ded0877
--- /dev/null
+++ b/README.md
@@ -0,0 +1,85 @@
+# slackware-changelog
+
+Shows the latest [Slackware -current](https://mirrors.slackware.com/slackware/slackware64-current/ChangeLog.txt)
+ChangeLog entry: date, how many packages moved, and how many carry a security
+fix.
+
+Homepage's `customapi` widget speaks JSON only, and the ChangeLog is plain
+text: several thousand lines covering years of entries, of which only the
+first block is wanted. This proxy fetches it, parses the latest entry, caches
+it so the widget refresh does not hit the mirror, and serves the fields.
+
+Stdlib Python, no dependencies, one file.
+
+## Features
+
+- Counts per action: upgraded, rebuilt, added, removed
+- Security fixes counted, and the CVE ids of the entry collected
+- The full entry as a readable page, linked from the card
+- A second card listing the packages themselves, truncated with a "... and N more" row
+- An unreachable mirror serves the last good entry, flagged as stale, rather than a blank card
+
+## Endpoints
+
+| Path | Returns |
+|---|---|
+| `/latest` (or `/`) | Date, counts, one-line summary, CVE ids |
+| `/top` | The first `TOP_N` packages as flat `pkg1..pkgN` fields, plus an overflow row. `?n=` overrides |
+| `/packages` | Every package in the entry, with its action |
+| `/entry` | The full entry as HTML |
+| `/refresh` | Same as `/latest`, ignoring the cache |
+
+## Install
+
+Runs on the machine hosting Homepage, listening on `127.0.0.1:8098`.
+
+```bash
+install -Dm755 slackware_changelog.py /opt/slackware-changelog/slackware_changelog.py
+install -Dm644 slackware-changelog.service /etc/systemd/system/slackware-changelog.service
+# edit the unit if you want a nearer mirror
+systemctl daemon-reload && systemctl enable --now slackware-changelog
+curl -s localhost:8098/latest
+```
+
+Then merge `homepage-services.yaml` into Homepage's `services.yaml` and the
+`layout:` block from `homepage-settings.yaml` into its `settings.yaml`, and
+restart Homepage.
+
+## Configuration
+
+Environment variables, set in the unit file:
+
+| Variable | Default | Meaning |
+|---|---|---|
+| `CHANGELOG_URL` | `https://mirrors.slackware.com/.../slackware64-current/ChangeLog.txt` | Use a nearer mirror, or `slackware-current` for 32-bit |
+| `PORT` | `8098` | Listen port, bound to localhost |
+| `CACHE_TTL` | `1800` | Seconds before the mirror is fetched again |
+| `TOP_N` | `8` | Packages listed by `/top` before it truncates |
+
+## Parsing
+
+An entry runs from the top of the file to the first `+----+` separator line.
+Inside it, a package line starts at column 0 and reads `path/name.txz:  Action.`;
+indented lines below it are free-text notes, which is why the parser anchors
+on the column and not on the trailing period. Notes are kept in the entry text
+but never counted as packages.
+
+## Tests
+
+```bash
+python3 test_changelog.py
+```
+
+Fakes the mirror, so it needs no network. Prints `ok`.
+
+## License
+
+GPLv2. See [LICENSE](LICENSE).
+
+## Development Approach
+
+This project is developed using AI-assisted tools. Code is generated with the help of AI based on human-provided specifications, design decisions, and iterative feedback.
+
+All contributions are reviewed, tested, and curated by the maintainer before being included in the codebase. AI is used as a productivity and exploration tool, while human oversight remains central to all decisions.
+
+The goal is to combine the flexibility of AI-assisted development with standard open-source practices such as transparency, review, and accountability.