feat: add stats helper service

Periodically snapshots Gitea instance metrics from a read-only MySQL
user and writes stats.json into Gitea custom/public/assets for the
home page to fetch same-origin. Config via env vars only.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

README.md

@@ -0,0 +1,50 @@
+# GiteaHelpers
+
+Helper services and tooling for the **Hangman Lab** Gitea instance
+(`git.hangman-lab.top`).
+
+## `stats/` — instance metrics collector
+
+A tiny Go service that periodically snapshots Gitea instance metrics from a
+**read-only** MySQL user and writes a static `stats.json` into Gitea's
+`custom/public/assets/` directory. Gitea then serves it same-origin at
+`/assets/stats.json`, which the custom home page fetches to render the
+metrics card. No HTTP endpoint is exposed to browsers; a local-only
+`/healthz` is provided for ops.
+
+Metrics: repositories, claw agents (non-admin users), commits in the last
+7 days, pull requests, merged pull requests.
+
+### Configuration (all via environment variables — no secrets in the image)
+
+| Env | Required | Default | Description |
+|-----|----------|---------|-------------|
+| `STATS_DB_DSN` | yes | — | MySQL DSN, e.g. `gitea_ro:PASSWORD@tcp(mysql:3306)/giteadb?timeout=5s&readTimeout=10s&loc=UTC` |
+| `STATS_OUT` | no | `/out/stats.json` | Output path (mount Gitea's `custom/public/assets` here) |
+| `STATS_INTERVAL` | no | `12h` | Refresh interval (Go duration) |
+| `STATS_ADDR` | no | `:8080` | Address for the local `/healthz` endpoint |
+
+The service fetches once on start, then every `STATS_INTERVAL`. On a failed
+refresh it keeps the previous output (stale-while-error).
+
+### Build & publish (image to the Gitea container registry)
+
+```sh
+# from repo root
+IMAGE=git.hangman-lab.top/hzhang/gitea-stats TAG=0.1.0 ./publish.sh
+```
+
+### Run
+
+```sh
+docker run -d --name git-kc-stats \
+  --network git-kc-net \
+  -e STATS_DB_DSN='gitea_ro:***@tcp(mysql:3306)/giteadb?timeout=5s&readTimeout=10s&loc=UTC' \
+  -e STATS_INTERVAL=12h \
+  -v /var/lib/gitea/custom/public/assets:/out \
+  git.hangman-lab.top/hzhang/gitea-stats:0.1.0
+```
+
+> The read-only MySQL user (`gitea_ro`, `SELECT` only on `giteadb`) and its
+> password are provisioned out-of-band; the password is passed only through
+> `STATS_DB_DSN` at runtime and is never committed.