mkaito — personal Gentoo overlay

Local Portage overlay (repo_name = mkaito). Packages Gentoo doesn't ship, or that were last-rited upstream, plus a few binary repacks. Single-user; not shaped for public consumption.

Portage reads it in place via /etc/portage/repos.conf/local.conf ([mkaito], location = /home/chris/dev/portage, auto-sync = no), which the dotfiles system-config deploy writes (mise run system:common on the gentoo host). Edit ebuilds here; portage sees them directly. Push to forgejo for backup. Needs guru configured too: it is a master (app-misc/1password-cli, whose group this overlay overrides).

Tasks

mise run update                                # bump + stage every outdated package
mise run update -- --dry-run                   # version table only, change nothing
mise run update -- games-util/rimsort          # one package
mise run update -- --accept net-im/loaf-chat   # bump despite its review gate
mise run vendor                                # (re)generate vendor tarballs
mise run vendor -- --force                     # ... overwriting existing ones
mise run check                                 # every pre-commit hook, whole tree

The table reports ok / OUTDATED current -> latest / CHECK current ?? latest (version not auto-comparable, e.g. date-stamped repacks) / skip (no upstream) / ERROR. GitHub calls authenticate with GH_TOKEN/GITHUB_TOKEN, else gh auth token, else go unauthenticated (60 requests/hour).

Tests: ruby .mise/test/update_test.rb.

update refuses a dirty working tree. Per outdated package, in parallel: rename the ebuild to the new version (dropping -rN), build the vendor tarball if the package has files/make-vendor.sh, ebuild … manifest, pkgcheck scan (any output fails). A failed step, or Ctrl-C, rolls that package back. Then it stages each bump (git add -A -- <cat>/<pkg>), deletes vendor tarballs whose version has no ebuild, and prints one git commit … -- <cat>/<pkg> per bump plus the sudo emerge line. It never commits or emerges. Logs, patches and verdicts go to a printed temp dir. Exits non-zero if anything was held, failed or errored (--dry-run: outdated or errored).

Hooks

Run pre-commit install once per clone; tools come from mise.toml. Hooks: standardrb + the update tests for .mise/ Ruby, shfmt (-ci) + shellcheck for the vendor scripts, rustup and magnetar-config, tab-indented xmllint --format for XML, and pkgcheck scan of the packages a commit touches, where any finding fails. eclass/, metadata/ or profiles/ changes scan the whole tree, so commit those with no other bumps staged. pkgcheck's ignored keywords live in metadata/pkgcheck.conf. Not checked: mise.sh (zsh/bash polyglot), mise.fish, OpenRC scripts.

Update source per package

update resolves each package's upstream from, in order:

1. an # UPDATE: directive comment in the (newest) ebuild,
2. else the first <remote-id type="github"> in metadata.xml,
3. else it's skipped (no trackable upstream).

Directive grammar:

# UPDATE: github <owner>/<repo> [tags] [mame] [pin=<EBUILD_VAR>] [check]
# UPDATE: factorio <stable|experimental>
# UPDATE: 1password
# UPDATE: skip [reason]

Exactly that spelling. Any other comment line starting # update: (any case or spacing), an unknown token, or a second directive makes the package ERROR.

• tags — use the repo's tags instead of releases/latest.
• mame — map mame0289 tags to PV 0.289.
• pin=<VAR> — compare an ebuild variable's value instead of PV. Never bumped automatically (held as manual).
• check — never claim ok/outdated; always show both (for PVs that don't map to upstream tags). Held as manual.

Add a directive when the github remote-id isn't the thing to track, or the version mapping is non-trivial. Plain github packages need nothing.

Review gate

.mise/review/<cat>/<pkg>.md exists ⇒ the package is gated. First line paths: <prefix> ... (upstream paths that need judgement), rest is the checklist. If the release diff (GitHub compare, old tag...new tag) touches a prefix, or lists 300+ files (the compare API's cap), the package is held and claude -p (Haiku, no tools, $0.50 cap) reads the diff against the checklist, answering MECHANICAL or NEEDS-WORK. After reading the verdict: --accept <cat>/<pkg>, or fix the ebuild by hand. A checklist for a missing package, a malformed paths: line, or a gated package without a GitHub upstream is an error.

Updating

1. mise run update.
2. Held packages: read the verdict, then re-run with --accept or bump by hand. Binary repacks with in-ebuild version/SHA constants need those bumped by hand.
3. Paste the printed git commit lines.
4. Paste the printed sudo emerge line.