# 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.