azy5030-overlay/CLAUDE.md

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## What this is

A personal **Gentoo ebuild repository (overlay)**, repo name `azy5030`, EAPI 8,
`masters = gentoo`, thin + unsigned Manifests (`metadata/layout.conf`). It packages
software not in the main `::gentoo` tree. Currently one package:
`dev-util/gitea-runner`. Hosted on a self-hosted Gitea at `git.azy.dev`. (This repo
is a standard SHA-1 repo; the sibling `homeserver` repo is SHA-256, so workflow
snippets copied from it may carry a `GIT_DEFAULT_HASH: sha256` checkout override
that this repo must *not* use.)

## The vendored-build model (the core design)

`dev-util/gitea-runner` is a `go-module` ebuild built **offline** from upstream
`gitea/runner` source. Gentoo's build sandbox has no network, so Go modules cannot be
fetched at build time. Instead they are vendored ahead of time:

1. The upstream source archive is `SRC_URI`'d from gitea.com's `/api/v1/.../archive`
   endpoint (a plain `git clone`/`go get` is never used).
2. A **vendor tarball** (`${P}-vendor.tar.xz`, the result of `go mod vendor`, packed
   deterministically) is uploaded as a **release asset on this repo** and is the second
   `SRC_URI`. `S="${WORKDIR}/runner"`.
3. `dev-util/gitea-runner/Manifest` pins BLAKE2B/SHA512 of both tarballs. `emerge`
   verifies against the Manifest, then compiles offline from `vendor/`.

Consequences when editing the ebuild:

- `LICENSE` must cover **every vendored module's** license, not just upstream's MIT.
  The bump PR checklist suggests `go-licenses report ./...` to confirm.
- `BDEPEND` Go version tracks upstream's `go.mod` `go` directive.
- The version string is injected via ldflags into
  `gitea.com/gitea/runner/internal/pkg/ver.version`; CI asserts `gitea-runner --version`
  echoes `v${PV}`. If upstream moves that symbol path, the build "succeeds" but reports
  the wrong version.

## Bumping to a new upstream version

This is **automated** by `scripts/bump-version.sh` (run daily by `bump.yaml`, or
`workflow_dispatch`). To do it manually you must reproduce its steps, because a version
bump is never just renaming the ebuild — the vendor tarball must be regenerated and
re-uploaded as a release asset, or the build will fail Manifest verification. The script:

1. Reads the latest `vX.Y.Z` from upstream `releases.rss`; compares to the newest
   committed ebuild. Exits early if up to date or if a `bump/gitea-runner-<ver>` branch
   already exists.
2. Downloads the source archive, runs `go mod vendor`, packs a reproducible
   `*-vendor.tar.xz` (`--sort=name --mtime='UTC 1970-01-01' --owner=0 --group=0`).
3. Creates/reuses a release tagged `${PN}-${ver}-vendor` and uploads the tarball asset.
4. `git mv`s the ebuild to the new version, rewrites `BDEPEND`'s Go version from
   upstream `go.mod`, and regenerates the Manifest with `pkgdev manifest` (after copying
   both distfiles into `/var/cache/distfiles` and wiring a temporary `repos.conf`).
5. Commits, pushes the branch, opens a PR against `master`. The script does **not**
   emerge or pkgcheck the result itself: the branch push triggers CI, which does both
   (and fetches the real release asset, which the script's local copy never would).

Requires a `BUMP_TOKEN` repo secret (scopes: repository read/write, write release) plus
a Gentoo env with `go pkgdev git curl xz jq`.

## CI (`.gitea/workflows/ci.yaml`)

Runs on every push, two jobs. A **`lint`** job runs on the plain Docker-backend runner
(no container), checks out with `actions/checkout`, installs the linters, and runs
`just lint` (markdownlint/shellcheck/yamllint/actionlint). The **`build`** job has
`needs: lint` (lint is a gate) and runs inside a `gentoo/stage3:amd64-openrc` container:
`emerge-webrsync` to sync `::gentoo` → configure portage (disables binpkg signature
verification so prebuilt deps like `dev-lang/go` are pulled, not compiled) → **check out
via `curl + tar`, not `actions/checkout`** into `/var/db/repos/azy5030` → `pkgcheck scan`
→ `emerge` → assert `gitea-runner --version` matches the ebuild version.

The build job can't use `actions/checkout` (even though the lint job does): the Gitea
runner executes JS actions by `docker exec node …` *inside* the job container, and
`gentoo/stage3` ships no node, so any JS action fails with exit 127. The lint job has no
`container:`, so it runs in the runner's default node-capable image and checkout works.

## Vendor-tag repointing (`.gitea/workflows/vendor-tags.yaml`)

The bump script creates the `${PN}-${ver}-vendor` release before the bump commit
exists, so its tag points at whatever `master` was at the time (and squash/rebase
merges mean the branch commit never lands on `master` anyway). On every push to
`master` touching `dev-util/**`, this workflow force-updates each vendor tag whose
ebuild is still in the tree to the `master` commit that added that ebuild. It only
ever *updates* tags: deleting a release's tag makes Gitea delete the release and its
assets, breaking the ebuild's `SRC_URI`. Tag pushes don't re-trigger CI because
`ci.yaml` is filtered to branch pushes.

## Conventions / gotchas

- **YAML** is linted by `.yamllint.yaml` (relaxed: line-length and document-start
  disabled; `truthy.check-keys: false` so `on:` is allowed unquoted).
- `metadata/md5-cache/` is **gitignored** — portage regenerates it on sync, so never
  commit it (a stale `gitea-runner-1.0.4` file may linger on disk untracked).
- The bump script and CI deliberately preserve the scheme of `GITHUB_SERVER_URL`: on the
  self-hosted runner it is an internal `http://` endpoint. Don't hardcode `https`.
- New packages must be added to `profiles/categories` (currently just `dev-util`).