fix: harden avatar fetching, output contract, and API handling

Review of the v0.1.0 surface turned up two ways an action run could stall or
be subverted, plus a set of behaviours that contradicted the documented ones.

- Avatar workers no longer die on exceptions outside AvatarError (malformed
  Content-Type, TLS failures, unreadable files): those killed the fiber and
  left the collector blocked until the job timed out.
- Release tags are validated and passed through env, so a crafted tag cannot
  reach a shell in the publishing job.
- Local avatars are resolved with realpath and size-capped; redirects must
  stay on public https, and only image content types reach the data URI.
- Nothing is written when a render would be empty or a later output fails,
  so a good wall is never replaced by a blank one.
- Sources compose: members/stargazers/sponsors work without a users list, a
  person found in several sources appears once with the highest weight, and
  config entries keep their own group.
- API errors are typed: 5xx retries, non-JSON bodies and hidden sponsors
  become ApiError, and a stalled GraphQL cursor ends pagination.
- Labels widen the canvas instead of being clipped, truncate: 0 disables
  truncation everywhere, and honeycomb/mosaic shrink to their content.
- Outputs always report changed/paths; png.scale accepts integers; enum and
  no_commit mistakes fail with the accepted values.

Author: hahwul

.github/workflows/ci.yml

@@ -5,6 +5,9 @@ on:
     branches: [main]
   pull_request:
 
+permissions:
+  contents: read
+
 jobs:
   test:
     runs-on: ubuntu-latest
@@ -44,3 +47,26 @@ jobs:
             hall-of-fame:ci
           grep -q "data:image" /tmp/ws/wall.svg
           head -c 4 /tmp/ws/wall.png | grep -q PNG
+
+  # Exercises the public entry point (action.yml) the way a consumer does;
+  # the docker job above bypasses it by running the image directly.
+  action:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - name: Prepare a workspace config
+        run: |
+          mkdir -p .github
+          printf 'users:\n  - login: hahwul\n  - login: octocat\noutput: ci-wall.svg\n' \
+            > .github/hall-of-fame.yml
+      - name: Run the action
+        id: hof
+        uses: ./
+        with:
+          no_commit: "true"
+      - name: Check outputs
+        run: |
+          test "${{ steps.hof.outputs.paths }}" = "ci-wall.svg"
+          test "${{ steps.hof.outputs.user_count }}" = "2"
+          test "${{ steps.hof.outputs.changed }}" = "false"
+          grep -q "data:image" ci-wall.svg

.github/workflows/release.yml

@@ -20,9 +20,16 @@ jobs:
           registry: ghcr.io
           username: ${{ github.actor }}
           password: ${{ secrets.GITHUB_TOKEN }}
+      # Reject anything that is not a plain semver tag before it reaches a
+      # shell, a docker tag list, or a git ref downstream.
       - name: Compute tags
         id: meta
-        run: echo "major=${GITHUB_REF_NAME%%.*}" >> "$GITHUB_OUTPUT"
+        run: |
+          case "$GITHUB_REF_NAME" in
+            v[0-9]*.[0-9]*.[0-9]*) ;;
+            *) echo "refusing malformed release tag: $GITHUB_REF_NAME" >&2; exit 1 ;;
+          esac
+          echo "major=${GITHUB_REF_NAME%%.*}" >> "$GITHUB_OUTPUT"
       - name: Build and push image
         uses: docker/build-push-action@v6
         with:
@@ -36,9 +43,17 @@ jobs:
 
       # The image must exist before the moving major tag points at a commit
       # whose action.yml references it.
+      # MAJOR goes through env, never `${{ }}` inside the script: a tag named
+      # `v1$(...)` would otherwise be substituted into the shell and run.
       - name: Move major version tag
+        env:
+          MAJOR: ${{ steps.meta.outputs.major }}
         run: |
+          case "$MAJOR" in
+            v[0-9]*) ;;
+            *) echo "refusing unexpected major tag: $MAJOR" >&2; exit 1 ;;
+          esac
           git config user.name "github-actions[bot]"
           git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
-          git tag -f "${{ steps.meta.outputs.major }}"
-          git push origin "${{ steps.meta.outputs.major }}" --force
+          git tag -f "$MAJOR"
+          git push origin "$MAJOR" --force

README.md

@@ -6,6 +6,8 @@ Generate avatar-wall art for your repository — a "hall of fame" of the people
 | :--: | :-------: | :----: |
 | ![grid](examples/grid.svg) | ![honeycomb](examples/honeycomb.svg) | ![mosaic](examples/mosaic.svg) |
 
+*(Curated samples from [`examples/showcase.yml`](examples/showcase.yml). This repository also runs the action on itself every week — the live result lands in [`docs/`](docs/).)*
+
 - **Three styles** — classic grid (circle/rounded/square), honeycomb hexagons, and a weight-tiered mosaic where your top contributors literally loom larger.
 - **Many sources, one wall** — your curated `users` list, repository contributors, org members, stargazers, and GitHub Sponsors (tier amounts become weights). Mix freely; your YAML entries always win.
 - **Sections & roles** — split the wall into titled groups (say, *Contributors* and *Special Thanks*) and tag people with a role line (*Creator*, *Design*, *Docs*) — made for honoring the folks the contributors API can't see.
@@ -20,7 +22,7 @@ Create `.github/hall-of-fame.yml`:
 ```yaml
 source: both              # my list + repository contributors
 style: grid
-output: HALL_OF_FAME.svg
+output: HALL_OF_FAME.svg  # or drop this and use `outputs:` for several files
 
 users:
   - login: hahwul
@@ -64,12 +66,12 @@ Then embed the result in your README:
 
 | Input | Default | Description |
 | ----- | ------- | ----------- |
-| `config` | `.github/hall-of-fame.yml` | Path to the config YAML |
-| `token` | `${{ github.token }}` | Token for the contributors API (`source: contributors`/`both`) |
-| `no_commit` | `false` | Generate files but skip commit/push |
+| `config` | `.github/hall-of-fame.yml` | Path to the config YAML, relative to the repository root |
+| `token` | `${{ github.token }}` | GitHub API token. Required for `sponsors`; also lifts rate limits and reaches private repos for the other API sources |
+| `no_commit` | `false` | Generate files but skip commit/push (must be `true` or `false`) |
 | `commit_message` | `chore: update hall of fame` | Commit message |
 
-Outputs: `svg_path` (comma-separated generated paths), `user_count`, `changed` (whether a commit was pushed).
+Outputs: `paths` (comma-separated generated files, SVG and PNG), `user_count`, and `changed` (whether a commit was pushed; `false` when `no_commit` is set). `svg_path` still works as an alias for `paths`.
 
 ## Configuration
 
@@ -162,11 +164,16 @@ png:
   scale: 2                  # rasterization zoom for .png outputs
 ```
 
-When `source: both`, your `users` entries win over API data field by field — set a custom `name` or `weight` while the contribution count fills everyone else's. Users without a `group` render first in an untitled section; groups follow the `groups` order (or first mention in the config). This is the recipe for honoring people the API misses — unlinked commit emails, design or docs work: add them to `users` with a `role` and their own section.
+When `source: both`, your `users` entries win over API data field by field — set a custom `name` or `weight` while the contribution count fills everyone else's. Placement is always yours: an entry without `group` renders in the untitled leading section even if the API put that person in one, so add `group:` when you want them filed under a heading. Someone returned by more than one API source (a contributor who also sponsors) appears once, keeping the highest weight and the first source's group.
+
+This is the recipe for honoring people the API misses — unlinked commit emails, design or docs work: add them to `users` with a `role` and their own section.
 
 ## Notes
 
+- A config file is required; the action fails if `.github/hall-of-fame.yml` (or the path you pass as `config`) does not exist.
 - The workflow needs `permissions: contents: write` to push the generated file, and a `concurrency` group avoids racing pushes on busy repositories.
+- Avatars link to profiles and carry name/role tooltips, but a README embed (`![](wall.svg)`) renders as an `<img>`, where neither is active. Open the SVG directly — or inline it — to get links.
+- `members` returns public organization members only; a token with `read:org` is needed for the rest. Stargazers arrive oldest-first with no weight, so under the default `sort: weight` they trail contributors — use `sort: none` to keep the API order.
 - On `pull_request` events the checkout is a detached HEAD, so pushes fail — use push/schedule/dispatch triggers, or set `no_commit: true` and handle the file yourself.
 - SVG size grows with user count (roughly 5–15 KB per avatar). Use `limit` and moderate avatar sizes for large walls.
 - With `mode: auto` (the default) the SVG contains both palettes and a `prefers-color-scheme` media query, so it follows GitHub's light/dark theme. PNGs can't adapt, so `.png` outputs pin `auto` to the light palette — add a second output with `mode: dark` for a pair.
@@ -179,10 +186,12 @@ The action binary is also a local CLI:
 
 ```bash
 shards build --release
-bin/hall-of-fame --config examples/showcase.yml   # writes examples/*.svg
+bin/hall-of-fame --config examples/showcase.yml   # regenerates the committed examples/*.svg
 bin/hall-of-fame -c my.yml --commit               # opt in to commit/push locally
 ```
 
+`--config` is resolved against the current directory, while output paths and local `avatar_url` files are resolved against `--workspace` (the current directory by default; `GITHUB_WORKSPACE` inside the action). Committing happens automatically when `GITHUB_ACTIONS=true` — including on runners that emulate it, such as act or Forgejo — and otherwise only with `--commit`.
+
 ## Development
 
 ```bash
@@ -193,7 +202,9 @@ crystal tool format
 bin/ameba src spec
 ```
 
-Release flow: pushing a `v*` tag builds a multi-arch image to `ghcr.io/crystal-actions/hall-of-fame` and force-moves the major tag (`v0`, `v1`, …). The image is pushed before the git tag moves, so the moving tag always references an existing image.
+Release flow: pushing a `vX.Y.Z` tag builds a multi-arch image to `ghcr.io/crystal-actions/hall-of-fame` and force-moves the major tag (`v0`, `v1`, …). The image is pushed before the git tag moves, so the moving tag always references an existing image.
+
+While the repository is private, `action.yml` still uses `image: Dockerfile`, so consumers build the image on their runner (roughly a minute on a cold cache) and the published GHCR image is not used yet. Switching `action.yml` to `docker://ghcr.io/crystal-actions/hall-of-fame:v0` is part of going public — runners pull GHCR anonymously, which only works once the package is public.
 
 ## License
 

action.yml

@@ -8,15 +8,18 @@ branding:
 
 inputs:
   config:
-    description: Path to the config YAML
+    description: Path to the config YAML, relative to the repository root
     required: false
     default: .github/hall-of-fame.yml
   token:
-    description: Token used for the contributors API (only needed for source contributors/both)
+    description: >-
+      Token for the GitHub API. Required for the sponsors source; also raises
+      rate limits and grants access to private repositories for the
+      contributors, members, and stargazers sources.
     required: false
     default: ${{ github.token }}
   no_commit:
-    description: Generate the files but skip commit/push
+    description: Generate the files but skip commit/push (must be true or false)
     required: false
     default: "false"
   commit_message:
@@ -25,12 +28,14 @@ inputs:
     default: "chore: update hall of fame"
 
 outputs:
+  paths:
+    description: Comma-separated paths of the generated files (SVG and PNG)
   svg_path:
-    description: Comma-separated paths of the generated SVG files
+    description: Deprecated alias for `paths`, kept for existing workflows
   user_count:
-    description: Number of users rendered
+    description: Number of users rendered in the last output
   changed:
-    description: Whether the files changed and were committed
+    description: Whether the files changed and were committed (false when no_commit is set)
 
 runs:
   using: docker